From c26e3473a4501149e62493b9fa1c31f07551123b Mon Sep 17 00:00:00 2001 From: redocly-bot Date: Fri, 31 Mar 2023 17:40:37 +0000 Subject: [PATCH] sync: Synced local 'docs/' with remote 'docs/redoc/' --- docs/deployment/cli.md | 114 +++++++-------------------------------- docs/deployment/intro.md | 4 +- 2 files changed, 20 insertions(+), 98 deletions(-) diff --git a/docs/deployment/cli.md b/docs/deployment/cli.md index ab4c860e..b6665446 100644 --- a/docs/deployment/cli.md +++ b/docs/deployment/cli.md @@ -4,111 +4,33 @@ redirectFrom: - /docs/redoc/quickstart/cli/ --- -# How to use the Redoc CLI +# How to use the Redocly CLI -With Redoc's command-line interface you can bundle your OpenAPI definition and API documentation -(made with Redoc) into a zero-dependency HTML file and locally render your -OpenAPI definition with Redoc. +With Redocly CLI, you can bundle your OpenAPI definition and API documentation +(made with Redoc) into a zero-dependency HTML file and render it locally. -## Step 1 - Install Redoc CLI +## Step 1 - Install Redocly CLI -You can install the `redoc-cli` package globally using one of the following package managers: +First, you need to install the `@redocly/cli` package. -- [npm](https://docs.npmjs.com/about-npm) -- [yarn](https://classic.yarnpkg.com/en/docs/getting-started) +You can install it [globally](/docs/cli/installation.md#global-installation) using npm or Yarn. -Or you can install `redoc-cli` using [npx](https://www.freecodecamp.org/news/npm-vs-npx-whats-the-difference/). +Or you can install it during [runtime](/docs/cli/installation.md#runtime-installation) using npx or Docker. -### Install Redoc CLI with yarn +## Step 2 - Build the HTML file -To install the `redoc-cli` package globally with yarn: +The Redocly CLI `build-docs` command builds Redoc into a zero-dependency HTML file. + +To build a zero-dependency HTML file using Redocly CLI, enter the following command, +replacing `apis/openapi.yaml` with your API definition file's name and path: ```bash -yarn global add redoc-cli +redocly build-docs apis/openapi.yaml ``` -### Install Redoc with npm +See the [build-docs](../../cli/commands/build-docs.md) documentation for more information +on the different options and ways you can use the command. -To install the `redoc-cli` package globally with npm: - -```bash -npm i -g redoc-cli -``` - -### Install with `npx` - -To install the `redoc-cli` package locally with `npx`, navigate to your project -directory in your terminal, then use the following command: - -```bash -npx redoc-cli -``` - -## Step 2 - Use the CLI - -### Redoc CLI commands - -The CLI includes the following commands: - -- **`redoc-cli serve [spec]`:** Starts a local server with Redoc. You must include the required parameter, spec, which is - a reference to an OpenAPI definition. Options include: - - `--ssr`: Implements a server-side rendering model. - - `--watch`: Automatically reloads the server while you edit your OpenAPI definition. - - `--options`: Customizes your output using [Redoc functionality options](https://redocly.com/docs/api-reference-docs/configuration/functionality) or [Redoc theming options](https://redocly.com/docs/api-reference-docs/configuration/theming). - To add nested options, use dot notation. -- **`redoc-cli build [spec]`:** Builds `spec` and Redoc into a zero-dependency HTML file. Options include: - - `-t` or `--template`: Uses custom [Handlebars](https://handlebarsjs.com/) templates to render your OpenAPI definition. - - `--templateOptions`: Adds template options you want to pass to your - custom Handlebars template. To add options, use dot notation. -- **`--help`:** Prints help text for the Redoc CLI commands and options. -- **`--version`:** Prints the version of the `redoc-cli` package you have installed. - -### Redoc CLI examples - -#### Bundle - -Bundle with the main color changed to `orange`: - -```bash -redoc-cli build openapi.yaml --options.theme.colors.primary.main=orange -``` - -Bundle using a custom Handlebars template and add custom `templateOptions`: - -```bash -redoc-cli build http://petstore.swagger.io/v2/swagger.json -t custom.hbs --templateOptions.metaDescription "Page meta description" -``` - -Sample Handlebars template: - -```handlebars - - - - - {{title}} - - - - - {{{redocHead}}} - {{#unless disableGoogleFont}}{{/unless}} - - - {{{redocHTML}}} - - -``` - -#### Serve - -Serve with the `nativeScrollbars` option set to `true`: - -```bash -redoc-cli serve openapi/dist.yaml --options.nativeScrollbars -``` +Also, check out [Redocly CLI commands](../../cli/commands/index.md), for more +information on the different things you can do with Redocly CLI including +linting, splitting, and bundling your API definition file. diff --git a/docs/deployment/intro.md b/docs/deployment/intro.md index b88b18b7..47cf6d54 100644 --- a/docs/deployment/intro.md +++ b/docs/deployment/intro.md @@ -21,8 +21,8 @@ The following options are supported: Using the React component is an option for users with a React-based application. - **[Docker image](./docker.md):** Using the Docker image works in a container-based deployment. -- **[CLI](./cli.md):** - Using the CLI is an option for users who prefer to use a command-line interface. +- **[Redocly CLI](./cli.md):** + Using the Redocly CLI is an option for users who prefer to use a command-line interface. ## Before you start