api2html

api2html

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

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

Installation

To install api2html globally, use

$ npm i api2html -g

You can also install it to use as devDependencies, and use it locally via a npm run task in your package.json:

$ npm i api2html --save-dev

Usage in package.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, source should be a url or a path
    -o, --out <outputPath>          output path for the resulting HTML document
    -t, --theme <themeName>         theme to use (see https://highlightjs.org/static/demo/ for a list)
    -c, --customLogo <logoPath>     use custom logo at the respective path
    -u, --customLogoUrl <logoURL>   url for the 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 use for the language tabs (out of shell, http, javascript, javascript--nodejs, ruby, python, java, go)
    -s, --search                    enable search
    -S, --summary                   use summary instead of operationId for TOC
    -b, --omitBody                  Omit top-level fake body parameter object
    -R, --raw                       Show raw schemas in samples, not example values
    -h, --help                      output usage information

Usage examples

Render OpenAPI v3 file as HTML

This will render the api.yml file in the current directory as myapi.html file in the current directory.

$ api2html -o myapi.html myapi.yml

Use custom logo

This will render the api.yml file in the current directory as myapi.html file in the same directory, and use the custom logo mylogo.png.

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

Define which language examples should be generated

This will render the api.yml file in the current directory as myapi.html file in the same directory, and use go and javascript examples.

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

Use different syntax highlighter

This will render the api.yml file in the current directory as myapi.html file in the same directory, and use go and javascript examples, as well as a different syntax higlighter from highlight.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