Build static API reference documentation

Benefits of using static API reference documentation

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.

Static API documentation benefits from 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 your organizational internal policies.
info

Redocly uses this tool within our own Workflows product.

What is reference-docs CLI?

The reference-docs CLI tool creates static API documentation (HTML, JS and CSS files) which opens instantly.

If you update your API definition, you will need to rebuild your documentation. For this purpose, you can set up a build step for each API definition change. This is exactly what our Workflows product does.

warning

This feature is only available in our Enterprise plans.

Install reference-docs CLI

  1. To obtain a license key, refer to the on-premise license key topic.
  2. Install the CLI tool with npm:
Copy
Copied
npm install @redocly/reference-docs --global

or with yarn

Copy
Copied
yarn global add @redocly/reference-docs
info

If you do not want to install the CLI tool, you can use npx.

Create static documentation

To create static documentation, run this command:

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

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

Advanced customization options

Copy
Copied
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]
warning

You will need version 1.1.3 or later for this to work.

Copy
Copied
reference-docs --version

Example with Try It console enabled

yamlbashbash
Copy
Copied
# sample Redocly configuration file

features.openapi:
  licenseKey: <insert your license key>
Copy
Copied
reference-docs build openapi.yaml
Copy
Copied
REDOCLY_LICENSE_KEY=<insert your license key> reference-docs build openapi.yaml