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

preview-docs

Introduction

With this command, you can preview the API reference docs 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 authenticate to the API registry first via the login command. :::

Usage

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

Options

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

Examples

Entrypoints

The command behaves differently depending on how you pass a path to 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 alias assigned in the apiDefinitions section within your .redocly.yaml configuration file as the entrypoint. For example, petstore:

openapi preview-docs petstore

apiDefinitions:
  petstore: ./openapi/petstore-definition.json

In this case, after resolving the path behind the petstore alias (example in the .redocly.yaml tab), preview-docs will preview the petstore.json definition file. For this approach, the .redocly.yaml configuration file is mandatory.

Custom configuration file

By default, the CLI tool looks for a .redocly.yaml 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

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