redocly-cli/docs/commands/preview-docs.md

preview-docs

Introduction

With this command, you can generate documentation previews for API definitions on your local machine.

If you have a license key or API key, you will get a preview of the premium Redocly API reference docs. If you don't, you will get a preview of Redoc community edition.

:::success Tip To preview docs using the premium Redocly API reference docs, you must first authenticate to the API registry with the login command. :::

Usage

openapi preview-docs <entrypoint> [branchName]
openapi preview-docs <entrypoint> [--config=<path>] [--port=<value>] [--host=<host>] [branchName]
openapi preview-docs <entrypoint> [--force] [--help] [--version] [branchName]
openapi preview-docs <entrypoint> --version

Options

Option	Type	Description
entrypoints	array	Path to the API definition filename or alias that you want to generate the preview for. Refer to the entrypoints section for more options.
--config	string	Specify path to the configuration file.
--force, -f	boolean	Generate preview output even when errors occur.
--help	boolean	Show help.
--port, -p	integer	Specify the port where the documentation preview can be accessed. You can set any port as long as it is not used by applications in your operating system. The default value is port 8080.
--host, -h	string	Specify the host where the documentation preview can be accessed. The default value is 127.0.0.1.
--skip-decorator	array	Ignore certain decorators.
--skip-preprocessor	array	Ignore certain preprocessors.
--use-community-edition	boolean	Force using Redoc Community Edition for docs preview.
--version	boolean	Show version number.

Examples

Entrypoints

The command behaves differently depending on how you pass the entrypoint to it, and whether the configuration file exists.

Pass entrypoint directly

openapi preview-docs openapi/openapi.yaml

In this case, preview-docs will preview the definition that was passed to the command. The configuration file is ignored.

Pass entrypoint alias

Instead of a full path, you can use an API name from the apis section of your Redocly configuration file as the entrypoint.

openapi preview-docs core@v1

apis:
  core@v1:
    root: ./openapi/definition.json

In this case, after resolving the path behind the core@v1 name (see the Configuration file tab), preview-docs generates a preview of the definition.json file. For this approach, the Redocly configuration file is mandatory.

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

openapi preview-docs --config=./another/directory/config.yaml

Custom port for preview

By default, without using the port option, the preview starts on port 8080, so you can access the docs at http://localhost:8080

To specify a custom port for the preview, pass the desired value using either short or long option format:

openapi preview-docs -p 8888 openapi/openapi.yaml

openapi preview-docs -port 8888 openapi/openapi.yaml

Both commands will start the preview on port 8888, so you can access the docs at http://localhost:8888

Custom host for preview

By default, without using the host option, the preview starts on host 127.0.0.1, so you can access the docs at http://127.0.0.1:8080 or http://localhost:8080

To specify a custom host for the preview, pass the desired value using either short or long option format:

openapi preview-docs -h 0.0.0.0 openapi/openapi.yaml

openapi preview-docs --host 0.0.0.0 openapi/openapi.yaml

Both commands will start the preview on host 0.0.0.0, so you can access the docs at http://0.0.0.0:8080

Skip preprocessor or decorator

You may want to skip specific preprocessors, rules, or decorators upon running the command.

openapi preview-docs --skip-preprocessor=discriminator-mapping-to-one-of,another-example

openapi preview-docs --skip-decorator=generate-code-samples,remove-internal-operations