diff --git a/docs/quickstart/cli.md b/docs/quickstart/cli.md new file mode 100644 index 00000000..10b12537 --- /dev/null +++ b/docs/quickstart/cli.md @@ -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 + + + + + {{title}} + + + + + {{{redocHead}}} + {{#unless disableGoogleFont}}{{/unless}} + + + {{{redocHTML}}} + + +``` + +#### Serve + +Serve with the `nativeScrollbars` option set to `true`: + +```bash +redoc-cli serve openapi/dist.yaml --options.nativeScrollbars +``` diff --git a/docs/quickstart/docker.md b/docs/quickstart/docker.md index 7359481b..31539fdb 100644 --- a/docs/quickstart/docker.md +++ b/docs/quickstart/docker.md @@ -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. \ No newline at end of file diff --git a/docs/quickstart/html.md b/docs/quickstart/html.md index 411cbce8..6da5561c 100644 --- a/docs/quickstart/html.md +++ b/docs/quickstart/html.md @@ -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 diff --git a/docs/quickstart/intro.md b/docs/quickstart/intro.md index 77675447..d1795604 100644 --- a/docs/quickstart/intro.md +++ b/docs/quickstart/intro.md @@ -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) diff --git a/docs/quickstart/react.md b/docs/quickstart/react.md index 9a4918f9..ebc19845 100644 --- a/docs/quickstart/react.md +++ b/docs/quickstart/react.md @@ -1,5 +1,5 @@ --- -title: React component +title: Using the Redoc React component --- # Using the Redoc React component diff --git a/docs/sidebars.yaml b/docs/sidebars.yaml index b5bf8b6c..2189f25b 100644 --- a/docs/sidebars.yaml +++ b/docs/sidebars.yaml @@ -8,4 +8,6 @@ redoc: - label: React component page: redoc/quickstart/react.md - label: Docker image - page: redoc/quickstart/docker.md \ No newline at end of file + page: redoc/quickstart/docker.md + - label: Command-line interface + page: redoc/quickstart/cli.md \ No newline at end of file