Redocly/redoc
1
1
Fork 0
mirror of https://github.com/Redocly/redoc.git synced 2025-08-06 13:20:19 +03:00
Code Issues Packages Projects Releases Wiki Activity

Adds redoc-cli section and updates from reviews

Browse Source
This commit is contained in:
Heather Cloward 2021-08-22 20:41:10 -04:00
parent 4e66af72bc
commit 13136cb291
6 changed files with 132 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
docs/quickstart/cli.md Normal file
View File

@ -0,0 +1,112 @@
---
title: Using the Redoc CLI
---
# Using the Redoc CLI
With Redoc's command-line interface you can locally render your
OpenAPI definition with Redoc and bundle your OpenAPI definition and Redoc into
a zero-dependency HTML file.
## Step 1 - Install Redoc CLI
You can install the `redoc-cli` package globally using one of the following package managers:
- [npm](https://docs.npmjs.com/about-npm)
- [yarn](https://classic.yarnpkg.com/en/docs/getting-started)
Or you can install `redoc-cli` using [npx](https://www.freecodecamp.org/news/npm-vs-npx-whats-the-difference/).
### Install Redoc CLI with yarn
To install the `redoc-cli` package globally with yarn, use the following command:
```sh
yarn global add redoc-cli
```
### Install Redoc with npm
To install the `redoc-cli` package globally with npm, use the following command:
```sh
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 options](https://redoc.ly/docs/api-reference-docs/configuration/).
To add nested options, use dot notation.
- **`redoc-cli bundle [spec]`:** Bundles `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`, using the following command:
```sh
redoc-cli bundle openapi.yaml --options.theme.colors.primary.main=orange
```
Bundle using a custom Handlebars template and add custom `templateOptions`:
```bash
redoc-cli bundle 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
```

8
docs/quickstart/docker.md
View File

@ -1,10 +1,10 @@
---
title: Using a Docker image
title: Using the Redoc Docker image
---
# Using the Redoc Docker image
Redoc is available as a pre-build Docker image in [Docker Hub](https://hub.docker.com/r/redocly/redoc/).
Redoc is available as a pre-built Docker image in [Docker Hub](https://hub.docker.com/r/redocly/redoc/).
If you have [Docker](https://docs.docker.com/get-docker/) installed, pull the image with the following command:
@ -32,6 +32,8 @@ For example:
docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc
```
You can also create a Dockerfile with some redefined environment variables. Check out
## Using a Dockerfile
You can also create a Dockerfile with some predefined environment variables. Check out
a sample [Dockerfile](https://github.com/Redocly/redoc/blob/master/config/docker/Dockerfile)
in our code repo.

9
docs/quickstart/html.md
View File

@ -1,5 +1,5 @@
---
title: Redoc HTML element
title: Using the Redoc HTML element
---
# Using the Redoc HTML element
@ -47,7 +47,7 @@ If you want to view your Redoc output locally, you can simulate an HTTP server.
#### Using Redocly OpenAPI CLI
Redocly OpenAPI CLI is an open source command-line tool that includes a command
for simulating an HTTP sever to provide a preview of your OpenAPI definition locally.
for simulating an HTTP server to provide a preview of your OpenAPI definition locally.
If you have [OpenAPI CLI](https://redoc.ly/docs/cli/#installation-and-usage) installed, `cd` into your
project directory and run the following command:
@ -59,7 +59,6 @@ openapi preview-docs openapi.yaml
By default, without providing a port, the preview starts on port 8080, and can be accessed at `http://localhost:8080`.
To exit the preview, use `control+C`.
#### Using Python
If you have [Python 3](https://www.python.org/downloads/) installed, `cd` into your
@ -76,7 +75,7 @@ project directory and run the following command:
python -m SimpleHTTPServer 8000
```
The output after entering the command provides the local where the preview can be accessed.
The output after entering the command provides the local URL where the preview can be accessed.
To exit the preview, use `control-C`.
#### Using Node.js
@ -94,7 +93,7 @@ Then, `cd` into your project directory and run the following command:
http-server
```
The output after entering the command provides the local where the preview can be accessed.
The output after entering the command provides the local URL where the preview can be accessed.
To exit the preview, use `control-C`.
## Step 1 - Install Redoc

12
docs/quickstart/intro.md
View File

@ -10,22 +10,24 @@ Redoc to render your OpenAPI definition.
Redoc offers multiple options for rendering your OpenAPI definition.
You should select the option that best fits your needs.
The different options include using the following:
The following options are supported:
- **[Live demo](/redoc/quickstart/live-demo.md):**
The live demo offers a fast way to see how your OpenAPI will render with Redoc.
- **[HTML element](/redoc/quickstart/html.md):**
Using an HTML element works well for typical website deployments.
Using the HTML element works well for typical website deployments.
- **[React component](/redoc/quickstart/react.md):**
Using a React component is an option for users with a React-based application.
Using the React component is an option for users with a React-based application.
- **[Docker image](/redoc/quickstart/docker.md):**
Using a Docker image works in a container-based deployment.
Using the Docker image works in a container-based deployment.
- **[CLI](/redoc/quickstart/cli.md):**
Using the CLI is an option for users who prefer to use a command-line interface.
## Before you start
You will need an OpenAPI definition. For testing purposes, you can use one of the following sample OpenAPI definitions:
- OpenAPI 3.0
- [Rebilly Users OpenAPI Definition](https://raw.githubusercontent.com/Rebilly/api-definitions/master/openapi/users.yaml)
- [Rebilly Users OpenAPI Definition](https://raw.githubusercontent.com/Rebilly/api-definitions/main/openapi/users.yaml)
- [Swagger Petstore Sample OpenAPI Definition](https://petstore3.swagger.io/api/v3/openapi.json)
- OpenAPI 2.0
- [Thingful OpenAPI Definition](https://raw.githubusercontent.com/thingful/openapi-spec/master/spec/swagger.yaml)

2
docs/quickstart/react.md
View File

@ -1,5 +1,5 @@
---
title: React component
title: Using the Redoc React component
---
# Using the Redoc React component

4
docs/sidebars.yaml
View File

@ -8,4 +8,6 @@ redoc:
- label: React component
page: redoc/quickstart/react.md
- label: Docker image
page: redoc/quickstart/docker.md
page: redoc/quickstart/docker.md
- label: Command-line interface
page: redoc/quickstart/cli.md