Converts a swagger-definition into a static html page. DEPRECATED (see below)
MIT License
This package is now deprecated, since I have moved all the functionality into the packages
The documentation of these packages, but the functionality is the same. Look at the example at bootprint-swagger to transform your swagger-definitions.
I think, Swagger is a great tool to document a REST-API, especially since it already has a nice documented user interface included. However, sometimes you need to deliver a static documentation to your customers. The first I did was use Swagger Codegen to create HTML and PhantomJS-rasterize to create a PDF.
There were however, some points that I didn't like about Swagger Codegen:
So swagger-to-html
Since almost every part of the module can be customized, it is very easy to circumvent bugs in the template and the styling by providing a customization for the buggy part. Please do submit bugs, if you find them. And if you make optimizations (especially ones from the todo-list below), please submit a pull request.
Customizations are meant for providing non-generic adaptions to customer needs. You can use them temporarily to resolve your generic problems, but if you think, your change would benefit everyone, please report them so that it can be fixed here too.
The package uses the commander
package to parse cli-parameters. If you call it without parameters, the following help page
will be displayed:
Usage: swagger-to-html [options] <swaggerfile> <targetdir>
Convert a swagger-definition file into a static html-page.
Options:
-h, --help output usage information
-V, --version output the version number
-f, --config-file <file> Specify a config file for custom configurations
-C, --no-css Omit css generation
-d, --development-mode Turn on file-watcher, less source maps and http-server with live-reload
A custom configuration-file can be specified. It must be a json-file and can contain options to customize the behaviour
of swagger-to-html
. The configuration-options are described below.
Without this option, swagger-to-html
will call lesscss
to combine the bootstrap
-less with the atom-light-syntax
-less
and other less-directives in this module. This is a time-consuming process and can be skipped, e.g. if you have already
generated you files before and have only changed your swagger-definition.
This option might disappear in the future. I'm thinking about using a fs-watcher to perform live-updates of the template and the css.
This options activates a development-mode. This means:
Note: Generally, chokidar is used in a non-polling mode if a whole directory is referenced in the configuration (partial templates and less-paths. For explicit files (swagger-file, less-files, directly referenced partials) the polling mode is used. Otherwise, there are problems with text-editors that use "atomic writes".
Note: Chrome does not seem to repaint the page, if only the CSS changes, until the mouse hovers over the browser window
// 'require' the module
var converter = require("swagger-to-html")({ /* options */ });
// call the lesscss-compiler to generate css
converter.generateCss(targetDir)
// call handlebars to generate the HTML-code
converter.generateHtml(swaggerJson, targetDir)
The development-mode cannot officially be activated programmatically at the moment
Disclaimer: I have not written any unit tests to verify these options yet. I am sure I will do so some time, but until then I cannot guarantee anything. You are welcome to test the options and submit bugs or even tests.
The configuration object can contain the following options:
{
partials: {
somePartialDirectory: "another/directory"
parameters: "...",
"...": "..."
},
template: "path/to/the/main/template.hbs",
helpers: {
aHandlebarsHelper: function(value) {
return 'result';
}
// '...'
}
less: {
paths: [ "path/to/an/include-directory/" ],
main: [ "path/to/a/less-file.less" ]
}
}
swagger-to-html
uses a Handlebars-template to convert the swagger-definition into a static html-page. The default template
is part of the module. The path to a custom template can be specified in this option.
This option contains an object of partial-definitions that a registered with Handlebars to be used by the template.
The recommended use of this option is the following:
{
partials: {
custom: "directory1"
}
}
With files directory1
containing file a.hbs
and b.hbs
, the registered partials, you can
us the following in you handlebars-template to call the partials.
Partial-A: {>custom/a}
Partial-B: {>custom/b}
The directory is traversed recursively, so there might appear partials like custom/subdir/c
as
well.
The following partials are included by default: (Warning! This list is outdated)
definitions
part of the swagger-json.Those can be overridden by specifying a partial-directory swagger-to-html
:
{
partials: {
custom: "directory1",
"swagger-to-html": "directory2",
}
}
Internally, this definition will be used to extend the default configuration to
{
partials: {
module1: [ "directory1" ],
"swagger-to-html": [ "template/partials", "directory2"],
}
}
All files in directory2
and template/partials
will now be registered as partials. If files
with the same name occur in both directories, they the later directory (i.e. directory2
)
overwrite previous definitions: If directory2
contains a single file
htmlBody.hbs
, it will override the default swagger-to-html/htmlBody
partial. All other
default partials are still being used.
Previous versions did not support partial-directories, but only partial-files.
{
partials: {
customPartial: "path/to/file.hbs"
}
}
Such configuration is now deprecated, but still works. If path/to/file.hbs
is not a
directory, but a regular file, the partial is registered by the entry's key (i.e. customPartial
).
However, partial-fils can not be used to override partials in partial-directories. One might think that the following should work:
{ partials: { "swagger-to-html/htmlBody": "path/to/file.hbs"} }
However, it is not defined, which file (the default-partial or the custom-partial)
is used in such a case. Entries of the partials
-object are processed in parallel,
so which partial overrides probably depends on the I/O timing for reading the directory and files.
It may also depend on the traversing order of the object's keys.
This object contains name-function mapping of Handlebars-helpers used by the template. Additional helpers can be provided and existing helpers can be overridden. The following helpers exist in the default configuration:
toUpperCase
: Generate uppercase letters of a string (used to write the HTTP-method)methodClass
: A mapping from HTTP-method to CSS-classmd
: Runs the input string through marky-markdown
to allow markdown-content in description properties.datatype
: Renders the "type" attribute of a parameter. Array types are rendered as type[]
json
: Used to render schema-properties. The javascript object defining the schema is json-stable-stringify
d.$ref
-tags pointing to #/definitions/...
are changed into links to the particular definition.This option is a list of additional lesscss include-paths. Use this option, if your main lesscss-file needs to @import files from some directories.
This option is an array of additional lesscss-files that can contain theme-adaptions. You can use it (for example) to specify different color schemes for the css. Take a look at the bootstrap documention to see what can be changed in the bootstrap-theme.
The less-file provided here, is imported after all other less-files in use, so you should be able to override all properties in here.
npm test
preventIndent
to fix wrong layout of <pre>
-tags (json-schema parts)