Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #361 from bandantonio/docs-preview-docs-command
Docs: fully revised preview-docs command for openapi-cli
- Loading branch information
Showing
1 changed file
with
82 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,39 +1,100 @@ | ||
# `preview-docs` | ||
|
||
Preview the API reference docs on your local machine. | ||
## Introduction | ||
|
||
If you have a license key, you will have a preview of the premium Redocly API reference docs. The [`login`](./login.md) command also generates a preview of the premium Redocly API reference docs. | ||
With this command, you can generate documentation previews for API definitions on your local machine. | ||
|
||
Otherwise, you'll get a preview of Redoc community edition. | ||
If you have a license key or API key, you will get a preview of the premium [Redocly API reference docs](https://redoc.ly/reference-docs). If you don't, you will get a preview of [Redoc community edition](https://redoc.ly/redoc). | ||
|
||
:::success Tip | ||
To preview docs using the premium Redocly API reference docs, you must first authenticate to the API registry with the [`login`](./login.md) command. | ||
::: | ||
|
||
### `preview-docs` usage | ||
## Usage | ||
|
||
```bash | ||
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](#entrypoints) for more options. | ||
`--config` | `string` | no | - | Specify path to the [config file](#custom-configuration-file) | ||
`--force`, `-f` | `boolean` | no | - | Generate preview output even when errors occur | ||
`--help` | `boolean` | no | - | Show help | ||
`--port`, `-p` | `number` | no | 8080 | 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. | ||
`--skip-decorator` | `array` | no | - | Ignore [certain decorators](#skip-preprocessor-or-decorator) | ||
`--skip-preprocessor` | `array` | no | - | Ignore [certain preprocessors](#skip-preprocessor-or-decorator) | ||
`--use-community-edition` | `boolean` | no | - | Force using Redoc Community Edition for docs preview | ||
`--version` | `boolean` | no | - | Show version number | ||
|
||
## Examples | ||
|
||
```shell | ||
Positionals: | ||
entrypoint [string] [required] | ||
### Entrypoints | ||
|
||
Options: | ||
--version Show version number. [boolean] | ||
--help Show help. [boolean] | ||
--port, -p Preview port. [number] [default: 8080] | ||
--skip-preprocessor Ignore certain preprocessors. [array] | ||
--skip-decorator Ignore certain decorators. [array] | ||
--use-community-edition Force using Redoc CE for docs preview. [boolean] | ||
--force, -f Produce bundle output even when errors occur. | ||
[boolean] | ||
--config Specify path to the config file. [string] | ||
The command behaves differently depending on how you pass a path to the entrypoint to it and whether the [configuration file](#custom-configuration-file) exists. | ||
|
||
#### Pass entrypoint directly | ||
|
||
```bash | ||
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. | ||
|
||
### How to preview the docs on a custom port | ||
#### Pass entrypoint alias | ||
|
||
By default, without providing a port, the preview starts on port 8080, and can be accessed at `http://localhost:8080`. | ||
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`: | ||
|
||
This command starts a preview on port 8888, and you can access the docs at `http://localhost:8888` after running it. | ||
```bash command | ||
openapi preview-docs petstore | ||
``` | ||
|
||
```yaml .redocly.yaml | ||
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. | ||
|
||
```bash | ||
openapi preview-docs --config=./another/directory/config.yaml | ||
``` | ||
|
||
```shell | ||
### 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: | ||
|
||
```bash short format | ||
openapi preview-docs -p 8888 openapi/openapi.yaml | ||
``` | ||
|
||
```bash long format | ||
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. | ||
|
||
```bash Skip preprocessors | ||
openapi preview-docs --skip-preprocessor=discriminator-mapping-to-one-of,another-example | ||
``` | ||
|
||
```bash Skip decorators | ||
openapi preview-docs --skip-decorator=generate-code-samples,remove-internal-operations | ||
``` |