Movatterモバイル変換

[0]ホーム
URL:

Skip to content
This is version picker select, using it you can select a version of the API.
Last updated

build-docs

Introduction

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

OpenAPI only

Thebuild-docs command currently supports only Swagger 2.0 and OpenAPI 3.0/3.1 descriptions. Support for OpenAPI 3.2 is coming soon.

Usage

redocly build-docs <api>redocly build-docs <api> --output=custom.htmlredocly build-docs <api> --theme.openapi.disableSearchredocly build-docs <api> --template custom.hbsredocly 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 tothe API section for more details.
--configstringPath to theconfiguration file. Defaults toredocly.yaml in the local folder.
--disableGoogleFontbooleanDisable Google fonts. The default value isfalse.
--helpbooleanShow help.
--lint-configstringSpecify the severity level for the configuration file. Possible values:warn,error,off. Default value iswarn.
--output, -ostringSet the path and name of the output file. The default value isredoc-static.html.
--template, -tstringUse customHandlebars templates to render your OpenAPI description.
--templateOptionsstringAdd template options you want to pass to your custom Handlebars template. To add options, use dot notation.
--theme.openapistringCustomize your output withRedoc functionality options orRedoc theming options.
--titlestringSet the page title.
--versionbooleanShow version number.

Examples

Specify API

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

Pass an API directly

redocly build-docs openapi.yaml

In this case, thebuild-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 theapis object of your Redocly configuration file. For example, with aredocly.yaml configuration file containing the following entry forgames@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 thegames@v1 name,build-docs generates a build of theapi-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 theRedocly 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

Hide search

The following command uses the optional--theme.openapi argument to build docs with the search box hidden:

redocly build-docs openapi.yaml --theme.openapi.disableSearch

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 usingtemplateOptions:

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

Sample custom Handlebars template:

<html>  <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}}}    {{#unless disableGoogleFont}}<link        href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700'        rel='stylesheet'      />{{/unless}}  </head>  <body>    {{{redocHTML}}}  </body></html>

Was this helpful?

 
Next page
[8]ページ先頭
©2009-2025 Movatter.jp