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
OR
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]
bundle spec into zero-dependency HTML-file
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, --spec-url Spec URL, URL for a download button, uses spec 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 (use with
routingStrategy: browser) [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
reference-docs build openapi.yaml
REDOCLY_LICENSE_KEY=<insert your license key> reference-docs build openapi.yaml