Creating static API reference documentation

Redocly CLI overview

What is static API reference documentation and why do we need it?

Static API documentation produces static HTML and CSS files based on your API definition.

The Redocly JS CDN builds the documentation on each page load. There is a performance penalty for doing that, which is magnified based on the size of the API definition.

Another benefit of static API documentation is SEO-friendly routes.

Use this when:

You have a large API definition, and page-load speed is really important.
You are using layout scope sections to give you SEO-friendly URLs and content.
You have an existing CI script for deployments which makes using a CLI tool a natural fit.
You cannot use Redocly's Workflows due to some internal policies.

Redocly uses this tool within our own Workflows product.

What is Redocly CLI?

Redocly CLI creates static API documentation (HTML, JS and CSS files) which opens instantly.

If you update your API definition, then the documentation needs to be rebuilt. For this purpose, you can set up a build step for each API definition change. This is exactly what our hosted "Workflows" product does.

Note: this tool is available in our enterprise plan.

Install CLI

Obtain the license key by contacting us.

Install CLI

npm install @redocly/reference-docs --global

yarn global add @redocly/reference-docs

If you do not want to install it, you can use npx.

Create static documentation

$ reference-docs build <path or url to api definition>

This will pre-render static files into redocly-static.

Advanced customization options

reference-docs build <api definition>

bundle definition into zero-dependency HTML-file [aliases: bundle]

Positionals:
  definition  path or URL to your OpenAPI Definition or config

Options:
  --help          Show help                                            [boolean]
  --version       Show version number                                  [boolean]
  --options       Redoc options, use dot notation, e.g. options.nativeScrollbars
                  or pass JSON value e.g. --options '{"nativeScrollbars": true}'
  -o, --output    Output dir                [string] [default: "redocly-static"]
  --title         Page Title           [string] [default: "Redoc documentation"]
  -u, --definition-url  API definition URL, URL for a download button,
                  uses API definition URL by default                    [string]
  -t, --template  Path to handlebars page template, see https://git.io/vh8fP
                  for the example                                       [string]
  -q, --query     Query params to use for downloading resources         [string]
  --prefix-paths  Overwrite routingBasePath Redoc setting
                                                          [string] [default: ""]
  --from-folder   Render all OpenAPI definitions in the folder
                                                          [string] [default: ""]
  --group-by      JSON pointer to grouping property inside the definition, e.g.
                  "info.x-domain"                         [string] [default: ""]
  --serve         Serve build artifacts after bundle  [boolean] [default: false]
  -p              Server port                           [number] [default: 3000]

Check to make sure you have version 1.1.3 or later.

reference-docs --version

Example with try it console enabled

# sample .redocly.yaml file
referenceDocs:
  licenseKey: <insert your license key>
  showConsole: true

bashbash

reference-docs build openapi.yaml

REDOCLY_LICENSE_KEY=<insert your license key> reference-docs build openapi.yaml