Redocly/redoc
1
1
Fork 0
mirror of https://github.com/Redocly/redoc.git synced 2024-11-25 01:53:44 +03:00
Code Issues Packages Projects Releases Wiki Activity

sync: Synced local 'docs/' with remote 'docs/redoc/'

Browse Source
This commit is contained in:
redocly-bot 2023-03-31 17:40:37 +00:00
parent d4cd6f7fbd
commit c26e3473a4
2 changed files with 20 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
docs/deployment/cli.md
View File

@ -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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf8" />
<title>{{title}}</title>
<!-- needed for adaptive design -->
<meta description="{{{templateOptions.metaDescription}}}">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
body {
padding: 0;
margin: 0;
}
</style>
{{{redocHead}}}
{{#unless disableGoogleFont}}<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">{{/unless}}
</head>
<body>
{{{redocHTML}}}
</body>
</html>
```
#### 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.

4
docs/deployment/intro.md
View File

@ -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