api2html

A CLI tool to transform Swagger/OpenAPI/AsyncAPI docs to beautiful HTML pages viaShins/Widdershins.

You can find an example generated page athttp://tobilg.github.io/api2html/petstore/.

Installation

To installapi2htmlglobally, use

$ npm i api2html -g

You can also install it to use asdevDependencies,and use it locally via anpm runtask in yourpackage.json:

$ npm i api2html --save-dev

Usage inpackage.json:

{
"scripts":{
"api-docs":"node_modules/.bin/api2html -o docs/api.html -l shell,javascript--nodejs docs/openapi/api.yml"
}
}

Usage

Available commands

$ api2html --help
Usage: api2html [options]<sourcePath>

Options:
-V, --version output the version number
-r, --resolve<source>resolve external dependencies,sourceshould be a url or a path
-o, --out<outputPath>output pathforthe resulting HTML document
-t, --theme<themeName>theme to use (see https://highlightjs.org/static/demo/fora list)
-c, --customLogo<logoPath>use custom logo at the respective path
-u, --customLogoUrl<logoURL>urlforthe custom logo to point to
-C, --customCss use custom css
-P, --customCssPath<cssPath>use custom css file
-i, --includes<includesList>comma-separated list of files to include
-l, --languages<languageList>comma-separated list of languages to useforthe language tabs (out of shell, http, javascript, javascript--nodejs, ruby, python, java, go)
-N, --noCodeSamples omit all code samples (overrides --languages)
-s, --searchenablesearch
-S, --summary use summary instead of operationIdforTOC
-b, --omitBody Omit top-level fake body parameter object
-R, --raw Show raw schemasinsamples, not example values
-h, --help output usage information

Usage examples

Render OpenAPI v3 file as HTML

This will render theapi.ymlfile in the current directory asmyapi.htmlfile in the current directory.

$ api2html -o myapi.html myapi.yml

Use custom logo

This will render theapi.ymlfile in the current directory asmyapi.htmlfile in the same directory, and use the custom logomylogo.png.

$ api2html -o myapi.html -c mylogo.png myapi.yml

Define which language examples should be generated

This will render theapi.ymlfile in the current directory asmyapi.htmlfile in the same directory, and usegoandjavascriptexamples.

$ api2html -o myapi.html -l go,javascript myapi.yml

Use different syntax highlighter

This will render theapi.ymlfile in the current directory asmyapi.htmlfile in the same directory, and usegoandjavascriptexamples, as well as a different syntax higlighter fromhighlight.js.

$ api2html -o myapi.html -l go,javascript -t arta myapi.yml

Resolve external dependencies

If you add refs to external files in your source file, you can enable them by using-r <source>.The following command will resolve all your relative imports from the current directory.

$ api2html -o myapi.html -r./ myapi.yml