Skip to content
Last updated

build-docs

Introduction

The build-docs command builds Redoc into an HTML file that contains your API documentation. The standalone HTML file can be easily shared or hosted on a platform of your choice.

The command supports Swagger 2.0, OpenAPI 3.0/3.1/3.2, AsyncAPI 2.x/3.x, and GraphQL schemas (.graphql or .gql files).

The page is rendered with Redoc 3 and loads the Redoc scripts from the Redocly CDN. Pass --inlineBundle to embed them, so the page works without loading the Redoc scripts from the CDN. Only the Redocly logo in the sidebar loads from the CDN.

The page sends Redoc telemetry from readers' browsers. To turn it off, build the page with REDOCLY_TELEMETRY=off or with telemetry: off in the configuration file.

Redoc options come from the configuration file key that matches the type of your API description: openapi, asyncapi, or graphql. The command also applies the decorators and preprocessors from the configuration file.

Upgrading from Redoc 2

Redoc 3 renamed or removed some Redoc 2 configuration options and replaced the Redoc 2 theme object with CSS custom properties. When you upgrade, review your Redoc settings against the Redoc configuration options and check your custom templates. Read what's new in Redoc 3 for details. To keep the Redoc 2 output, use Redocly CLI v1: npx @redocly/cli@v1-archive build-docs <api>.

Usage

redocly build-docs <api>
redocly build-docs <api> --output=custom.html
redocly build-docs <api> --inlineBundle
redocly build-docs <api> --openapi.hideDownloadButtons
redocly build-docs <api> --template custom.hbs
redocly build-docs <api> -t custom.hbs --templateOptions.metaDescription "Page meta description"

Options

OptionTypeDescription
apistringPath to the API description filename or alias that you want to generate the build for. Refer to the API section for more details.
--asyncapistringCustomize your output with Redoc AsyncAPI options. Use dot notation, for example --asyncapi.jsonSamplesDepth 4.
--configstringPath to the configuration file. Defaults to redocly.yaml in the local folder.
--graphqlstringCustomize your output with Redoc GraphQL options. Use dot notation, for example --graphql.showBuiltInScalars.
--helpbooleanShow help.
--inlineBundlebooleanEmbed the Redoc scripts into the output file instead of loading them from the Redocly CDN. The default value is false.
--lint-configstringSpecify the severity level for the configuration file. Possible values: warn, error, off. Default value is warn.
--openapistringCustomize your output with Redoc OpenAPI options. Use dot notation, for example --openapi.hideDownloadButtons.
--output, -ostringSet the path and name of the output file. The default value is redoc-static.html.
--template, -tstringUse custom Handlebars templates to render your API description.
--templateOptionsstringAdd template options you want to pass to your custom Handlebars template. To add options, use dot notation.
--titlestringSet the page title.

Examples

Specify API

The build-docs command behaves differently depending on how you pass the API to it, and whether the configuration file exists.

Pass an API directly

redocly build-docs openapi.yaml

In this case, the build-docs command builds the API description that was passed to the command. Even if a configuration file exists, the command does not check for APIs listed in it.

Pass an API alias

Instead of a full path, you can use an API name from the apis object of your Redocly configuration file. For example, with a redocly.yaml configuration file containing the following entry for games@v1:

apis:
  games@v1:
    root: ./openapi/api-description.json

You can generate a build by including the API name with the command, as shown in the following example:

redocly build-docs games@v1

In this case, after resolving the path behind the games@v1 name, build-docs generates a build of the api-description.json file. For this approach, the Redocly configuration file is mandatory. Any additional configurations provided in the file are also used by the command.

Use an alternative configuration file

By default, the CLI tool looks for the Redocly configuration file in the current working directory. Use the optional --config argument to provide an alternative path to a configuration file.

redocly build-docs --config=./another/directory/config.yaml

Configure Redoc

Each API description type reads its options from its own configuration file key, so one file can configure all three:

openapi:
  hideDownloadButtons: true
asyncapi:
  jsonSamplesDepth: 4
graphql:
  showBuiltInScalars: true

The matching command-line argument replaces the options from the configuration file:

redocly build-docs openapi.yaml --openapi.hideDownloadButtons

Use a custom template

The following command builds docs using a custom Handlebars template and adds metadata to the meta tag in the head of the page using templateOptions:

redocly build-docs ./openapi/api.yaml -t custom.hbs --templateOptions.metaDescription "Page meta description"

Sample custom Handlebars template:

<html lang='en'>
  <head>
    <meta charset='utf8' />
    <title>{{title}}</title>
    <!-- needed for adaptive design -->
    <meta description='{{{templateOptions.metaDescription}}}' />
    <meta name='viewport' content='width=device-width, initial-scale=1' />
    <style>
      body {
        padding: 0;
        margin: 0;
      }
    </style>
    {{{redocHead}}}
  </head>
  <body>
    {{{redocHTML}}}
  </body>
</html>

bundle