Building 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.

Another benefit of static API documentation i 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 Redocly CLI?

Redocly CLI 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.

Installing CLI

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

or with yarn

yarn global add @redocly/reference-docs
info

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

Creating static documentation

To create static documentation, run this command:

$ 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]
warning

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

reference-docs --version

Example with Try It console enabled

yamlbashbash
# sample .redocly.yaml file

referenceDocs:
 licenseKey: <insert your license key>
 showConsole: true
reference-docs build openapi.yaml
REDOCLY_LICENSE_KEY=<insert your license key> reference-docs build openapi.yaml