Specify a config file for custom configurations\n -C, --no-css Omit css generation\n -d, --development-mode Turn on file-watcher, less source maps and http-server with live-reload\n\n```\n\n### -f, --config-file\n\nA custom configuration-file can be specified. It must be a json-file and can contain options to customize the behaviour\nof `swagger-to-html`. The configuration-options are described [below](#configuration-options).\n\n### -C, --no-css\n\nWithout this option, `swagger-to-html` will call `lesscss` to combine the `bootstrap`-less with the `atom-light-syntax`-less\nand other less-directives in this module. This is a time-consuming process and can be skipped, e.g. if you have already\ngenerated you files before and have only changed your swagger-definition.\n\nThis option might disappear in the future. I'm thinking about using a fs-watcher to perform live-updates of the template and\nthe css.\n\n### -d, --development-mode\n\nThis options activates a development-mode. This means:\n\n* The template-files, all partials, all less-files and the swagger-file are watched using [the chokidar module](https://www.npmjs.com/package/chokidar). CSS and/or HTML are rebuilt automatically when needed.\n* A [live-server](https://www.npmjs.com/package/live-server) is run on the target directory to enable live-reloading html and css.\n* LESS source-maps are generated and inlined into the CSS.\n\n\n*Note: Generally, chokidar is used in a non-polling mode if a whole directory is referenced in the configuration (partial\ntemplates and less-paths. For explicit files (swagger-file, less-files, directly referenced partials) the polling mode is\nused. Otherwise, there are problems with text-editors that use \"atomic writes\".*\n\n*Note: Chrome does not seem to repaint the page, if only the CSS changes, until the mouse hovers over the browser window*\n\n## Programmatic usage\n\n```js\n\n// 'require' the module\nvar converter = require(\"swagger-to-html\")({ /* options */ });\n\n// call the lesscss-compiler to generate css\nconverter.generateCss(targetDir)\n\n// call handlebars to generate the HTML-code\nconverter.generateHtml(swaggerJson, targetDir)\n```\n\n*The development-mode cannot officially be activated programmatically at the moment*\n\n\n## Configuration options\n\n*Disclaimer: I have not written any unit tests to verify these options yet.\n I am sure I will do so some time, but until then I cannot guarantee anything.\n You are welcome to test the options and submit bugs or even tests.*\n\nThe configuration object can contain the following options:\n\n```js\n{\n partials: {\n somePartialDirectory: \"another/directory\"\n parameters: \"...\",\n \"...\": \"...\"\n },\n template: \"path/to/the/main/template.hbs\",\n helpers: {\n aHandlebarsHelper: function(value) {\n return 'result';\n }\n // '...'\n }\n less: {\n paths: [ \"path/to/an/include-directory/\" ],\n main: [ \"path/to/a/less-file.less\" ]\n }\n}\n```\n\n### template\n\n`swagger-to-html` uses a Handlebars-template to convert the swagger-definition into a static html-page. The default template\nis part of the module. The path to a custom template can be specified in this option.\n\n### partials\n\nThis option contains an object of partial-definitions that a registered with Handlebars to be used by the template.\n\nThe recommended use of this option is the following:\n\n* The key of each entry is the name-prefix of some partials.\n* The value of each entry contains a directory containing these partials.\n\n```js\n{\n partials: {\n custom: \"directory1\"\n }\n}\n```\n\nWith files `directory1` containing file `a.hbs` and `b.hbs`, the registered partials, you can\nus the following in you handlebars-template to call the partials.\n\n```hbs\nPartial-A: {>custom/a}\nPartial-B: {>custom/b}\n```\n\nThe directory is traversed recursively, so there might appear partials like `custom/subdir/c` as\nwell.\n\nThe following partials are included by default: (*Warning! This list is outdated*)\n\n* **swagger-to-html/htmlBody** renders the whole html-body contents.\n* **swagger-to-html/path** renders a single path definition.\n* **swagger-to-html/method** renders a single method definition.\n* **swagger-to-html/parameters** renders the request-parameters of a single request (path-method).\n* **swagger-to-html/responses** renders the response definitions of a request.\n* **swagger-to-html/definitions** renders the `definitions` part of the swagger-json.\n\nThose can be overridden by specifying a partial-directory `swagger-to-html`:\n\n```js\n{\n partials: {\n custom: \"directory1\",\n \"swagger-to-html\": \"directory2\",\n }\n}\n```\n\nInternally, this definition will be used to extend the default configuration to\n\n```js\n{\n partials: {\n module1: [ \"directory1\" ],\n \"swagger-to-html\": [ \"template/partials\", \"directory2\"],\n }\n}\n```\n\nAll files in `directory2` and `template/partials` will now be registered as partials. If files\nwith the same name occur in both directories, they the later directory (i.e. `directory2`)\noverwrite previous definitions: If `directory2` contains a single file\n`htmlBody.hbs`, it will override the default `swagger-to-html/htmlBody` partial. All other\ndefault partials are still being used.\n\n#### Deprecated configuration\n\nPrevious versions did not support partial-directories, but\nonly partial-files.\n\n```js\n{\n partials: {\n customPartial: \"path/to/file.hbs\"\n }\n}\n```\nSuch configuration is now deprecated, but still works. If `path/to/file.hbs` is not a\ndirectory, but a regular file, the partial is registered by the entry's key (i.e. `customPartial`).\n\nHowever, partial-fils can **not** be used to override partials in partial-directories.\nOne might think that the following should work:\n\n```js\n{ partials: { \"swagger-to-html/htmlBody\": \"path/to/file.hbs\"} }\n```\n\nHowever, it is **not defined**, which file (the default-partial or the custom-partial)\nis used in such a case. Entries of the `partials`-object are processed in parallel,\nso which partial overrides probably depends on the I/O timing for reading the directory and files.\nIt may also depend on the traversing order of the object's keys.\n\n### helpers (*Warning: List is outdated*)\n\nThis object contains name-function mapping of Handlebars-helpers used by the template. Additional\nhelpers can be provided and existing helpers can be overridden. The following helpers exist in the default configuration:\n\n* `toUpperCase`: Generate uppercase letters of a string (used to write the HTTP-method)\n* `methodClass`: A mapping from HTTP-method to CSS-class\n* `md`: Runs the input string through `marky-markdown` to allow markdown-content in description properties.\n* `datatype`: Renders the \"type\" attribute of a parameter. Array types are rendered as `type[]`\n* `json`: Used to render schema-properties. The javascript object defining the schema is `json-stable-stringify`d.\n `$ref`-tags pointing to `#/definitions/...` are changed into links to the particular definition.\n\n\n### less.paths\n\nThis option is a list of additional lesscss include-paths. Use this option, if your main lesscss-file needs\nto @import files from some directories.\n\n### less.main\n\nThis option is an array of additional lesscss-files that can contain theme-adaptions.\nYou can use it (for example) to specify different color schemes for the css. Take a look at\n[the bootstrap documention](http://getbootstrap.com/css/#less) to see what can be changed in the bootstrap-theme.\n\nThe less-file provided here, is imported after all other less-files in use, so you should be able\nto override all properties in here.\n\n## Module structure\n\n* **bin** contains the command-line-interface javascript\n* **src** contains the javascript-files source files\n* **example** contains the petstore-example and the generated html\n* **styles** contains the less-files adapting the bootstrap-theme\n* **templates** contains the default Handlebars-template and partials\n* **target** is the directory that is created when you run `npm test`\n* **tests** contains some unit tests\n\n## TODOs\n\n\n* Provide a more complex example with custom configuration file\n* The Handlebars template is not complete yet. Missing parts:\n * Tags\n * Most parts of the \"info\"-block are still missing.\n* Write unit tests\n* Include css-directives for [CSS Paged Media Module Level 3](http://www.w3.org/TR/css3-page/) in order to\n create a nicer print version (printable e.g. with [WeasyPrint](http://weasyprint.org)). This should include:\n * Appropriate page header- and footer-lines.\n * Cross-references containing page- or chapter-numbers\n* Include better navigation [affix](http://getbootstrap.com/javascript/#affix) for browser view and a table of contents\n for printing.\n* Production version with inlined css\n* Option to run WeasyPrint to generate a PDF.\n* **Extract the code part into its own module so that it can be reused with other templates**\n\n\n\n## Changelog\n\n#### 2015-03-12 - Version 0.3.0\n\n* Updated template and partials to draw a more readble version of the swagger-models.\n* Some template refactorings\n* Almost all labels and section headers are are now configurable in LESS\n* Fix for loading custom config file via command line.\n* Included custom-config-example in \"example\" TODO: document example\n\n\n#### 2015-03-08 - Version 0.2.3\n\n* Add Handlebars option `preventIndent` to fix wrong layout of ``-tags (json-schema parts)\n\n#### 2015-03-07 - Version 0.2.2\n\n* Update documentation\n* Possibility to specify strings as partial-directories (instead of arrays)\n* Fix broken programmatic usage\n\n#### 2015-03-05 - Version 0.2.1\n\n* Fix README markup for code examples\n\n#### 2015-03-05 - Version 0.2.0\n\n* Development mode with file-system-watcher, live-reload server and LESS-source-maps\n* Partial-configurations can now contain directories.\n* Use [marked](https://www.npmjs.com/package/marked), [highlight.js](https://www.npmjs.com/package/highlight.js)\n and [cheerio](https://www.npmjs.com/package/cheerio) instead of\n [marky-markdown](https://www.npmjs.com/package/marky-markdown). The latter does not seem to work on MS-Windows.\n\n#### 2015-03-02 - Version 0.1.0\n\n* Refactoring: More main template divided into more partials\n* Changing config-options for lesscss\n* Define custom css classes for method-headers (GET, POST, PUT, ...)\n\n#### 2015-03-01 - Version 0.0.2 - 0.0.5\n\n* Changes in README\n\n#### 2015-03-01 - Version 0.0.1\n\n* Initial version\n\n\n","maintainers":[{"name":"knappi","email":"npm@knappi.org"}],"time":{"modified":"2022-06-27T02:47:27.509Z","created":"2015-03-01T00:38:03.030Z","0.0.1":"2015-03-01T00:38:03.030Z","0.0.2":"2015-03-01T00:39:38.273Z","0.0.3":"2015-03-01T00:41:33.082Z","0.0.4":"2015-03-01T00:42:58.113Z","0.0.5":"2015-03-01T00:44:13.132Z","0.1.0":"2015-03-02T23:47:25.615Z","0.2.0":"2015-03-05T21:35:48.805Z","0.2.1":"2015-03-05T21:40:03.378Z","0.2.2":"2015-03-07T07:13:49.327Z","0.2.3":"2015-03-08T06:59:25.639Z","0.3.0":"2015-03-12T22:39:42.940Z","0.4.0":"2015-03-15T14:43:03.080Z"},"homepage":"https://github.com/nknapp/swagger-to-html","repository":{"type":"git","url":"https://github.com/nknapp/swagger-to-html.git"},"author":{"name":"Nils Knappmeier"},"bugs":{"url":"https://github.com/nknapp/swagger-to-html/issues"},"license":"MIT","readmeFilename":"README.md"}