preview-docs
Introduction
With this command, you can generate documentation previews for API descriptions on your local machine.
If you have a license key or API key configured, the output is a preview of the premium Redocly API reference docs. Otherwise, it is a preview of Redoc community edition.
Tip
To preview docs using the premium Redocly API reference docs, you must first authenticate to the API registry with the login
command.
Usage
redocly preview-docs <api>
redocly preview-docs <api> [--config=<path>] [--port=<value>] [--host=<host>]
redocly preview-docs <api> [--force] [--help] [--version]
redocly preview-docs <api> --version
Options
Option | Type | Description |
---|---|---|
api | string | Path to the API description filename or alias that you want to generate the preview for. Refer to the api 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. |
--host, -h | string | The host where the documentation preview can be accessed. The default value is 127.0.0.1 . |
--port, -p | integer | The port where the documentation preview can be accessed. You can set any port number over 1024 as long as it is not already being used. The default value is port 8080 . |
--skip-decorator | [string] | Ignore certain decorators. |
--skip-preprocessor | [string] | Ignore certain preprocessors. |
--use-community-edition | boolean | Use Redoc Community Edition for docs preview. |
--version | boolean | Show version number. |
Examples
Api
The command behaves differently depending on how you pass the api to it, and whether the configuration file exists.
Pass api directly
redocly preview-docs openapi/openapi.yaml
In this case, preview-docs
previews the API description that was passed to the command. The configuration file is ignored.
Pass api alias
Instead of a full path, you can use an API name from the apis
section of your Redocly configuration file.
redocly preview-docs core@v1
apis:
core@v1:
root: ./openapi/api-description.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 api-description.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.
redocly 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:
redocly preview-docs -p 8888 openapi/openapi.yaml
redocly preview-docs -port 8888 openapi/openapi.yaml
Both commands 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:
redocly preview-docs -h 0.0.0.0 openapi/openapi.yaml
redocly preview-docs --host 0.0.0.0 openapi/openapi.yaml
Both commands 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.
redocly preview-docs --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example
redocly preview-docs --skip-decorator=generate-code-samples --skip-decorator=remove-internal-operations