From bf6b85d4ba371b286d6cb9856352fac70bff5a64 Mon Sep 17 00:00:00 2001 From: redocly-bot Date: Tue, 23 Nov 2021 05:08:42 +0000 Subject: [PATCH] sync: Synced local 'docs/' with remote 'docs/redoc/' --- docs/quickstart/cli.md | 112 ++++++++++++++++++++ docs/quickstart/docker.md | 39 +++++++ docs/quickstart/html.md | 214 ++++++++++++++++++++++++++++++++++++++ docs/quickstart/intro.md | 44 ++++++++ docs/quickstart/react.md | 78 ++++++++++++++ 5 files changed, 487 insertions(+) create mode 100644 docs/quickstart/cli.md create mode 100644 docs/quickstart/docker.md create mode 100644 docs/quickstart/html.md create mode 100644 docs/quickstart/intro.md create mode 100644 docs/quickstart/react.md diff --git a/docs/quickstart/cli.md b/docs/quickstart/cli.md new file mode 100644 index 00000000..b0f2af85 --- /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 bundle your OpenAPI definition and API documentation +(made with Redoc) into a zero-dependency HTML file and locally render your +OpenAPI definition with Redoc. + +## 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: + +```bash +yarn global add redoc-cli +``` + +### Install Redoc with npm + +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 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`: + +```bash +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 new file mode 100644 index 00000000..31539fdb --- /dev/null +++ b/docs/quickstart/docker.md @@ -0,0 +1,39 @@ +--- +title: Using the Redoc Docker image +--- + +# Using the Redoc Docker image + +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: + +```docker +docker pull redocly/redoc +``` + +Then run the image with the following command: + +```docker +docker run -p 8080:80 redocly/redoc +``` + +The preview starts on port 8080, based on the port used in the command, +and can be accessed at `http://localhost:8080`. +To exit the preview, use `control+C`. + +By default Redoc starts with a demo Swagger Petstore OpenAPI definition located at +http://petstore.swagger.io/v2/swagger.json. You can update this URL using +the environment variable `SPEC_URL`. + +For example: + +```bash +docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc +``` + +## 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 new file mode 100644 index 00000000..bfc8d267 --- /dev/null +++ b/docs/quickstart/html.md @@ -0,0 +1,214 @@ +--- +title: Using the Redoc HTML element +--- + +# Using the Redoc HTML element + +## TL;DR final code example + +```html + + + + Redoc + + + + + + + + + + + + + + +``` + +:::attention Running Redoc locally requires an HTTP server +Loading local OpenAPI definitions is impossible without running a web server because of issues with +[same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) and +other security reasons. +::: + +### Running Redoc locally + +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 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: + +```bash +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 +project directory and run the following command: + +```python +python3 -m http.server +``` + +If you have [Python 2](https://www.python.org/downloads/) installed, `cd` into your +project directory and run the following command: + +```python +python -m SimpleHTTPServer 8000 +``` + +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 + +If you have [Node.js](https://nodejs.org/en/download/) installed, install `http-server` +using the following npm command: + +```bash +npm install -g http-server +``` + +Then, `cd` into your project directory and run the following command: + +```node +http-server +``` + +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 + +You can install Redoc using one of the following package managers: + +- [npm](https://docs.npmjs.com/about-npm) +- [yarn](https://classic.yarnpkg.com/en/docs/getting-started) + +:::attention Initialize your package manager +If you do not have a `package.json` file in your project directory, +you need to add one by initializing npm or yarn in your project. Use the command `npm init` for npm, +or `yarn init` for yarn. These initialization commands will lead you through the process +of creating a `package.json` file in your project. + +For more information, see +[Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file) +in the npm documentation or [Yarn init](https://classic.yarnpkg.com/en/docs/cli/init/) +in the yarn documentation. + +::: + +### Install Redoc with yarn + +After navigating to your project directory in your terminal, use the following command: + +```bash +yarn add redoc +``` + +### Install Redoc with npm + +After navigating to your project directory in your terminal, use the following command: + +```bash +npm i redoc +``` + +## Step 2 - Reference the Redoc script + +You can reference the Redoc script using either a link to the files hosted on a CDN +or the files located in your `node modules` folder. + +### CDN link + +To reference the Redoc script with a CDN link: + +```html + +``` + +### Node modules link + +To reference the Redoc script with a node modules link: + +```html + +``` + +## Step 3 - Add the element + +You can add the element to your HTML page and reference your OpenAPI +definition using the `spec-url` attribute, or you can initialize Redoc using +a globally exposed Redoc object. + +### Using the `spec-url` attribute + +To add the element with the `spec-url` attribute: + +```html + +``` + +#### Examples + +```html + +``` + +You can also use a local file (JSON or YAML) in your project, for instance: + +```html + +``` + +### Using a Redoc object + +To add the element with a globally exposed Redoc object: + +```js +Redoc.init(specOrSpecUrl, options, element, callback) +``` +- `specOrSpecUrl`: Either a JSON object with the OpenAPI definition or a URL to the + definition in JSON or YAML format. +- `options`: See [options object](https://redoc.ly/docs/api-reference-docs/configuration/) reference. +- `element`: DOM element Redoc will be inserted into. +- `callback`(optional): Callback to be called after Redoc has been fully rendered. + It is also called on errors with `error` as the first argument. + +#### Examples + +```html + +``` + +You can also use a local file (JSON or YAML) in your project, for instance: + +```html + +``` \ No newline at end of file diff --git a/docs/quickstart/intro.md b/docs/quickstart/intro.md new file mode 100644 index 00000000..e23f9d00 --- /dev/null +++ b/docs/quickstart/intro.md @@ -0,0 +1,44 @@ +--- +title: Redoc quickstart guide +--- + +# Redoc quickstart guide + +This guide includes step-by-step instructions for how to get started using +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 following options are supported: + +- **[Live demo](https://redocly.github.io/redoc/):** + The live demo offers a fast way to see how your OpenAPI will render with Redoc. +- **[HTML element](./html.md):** + Using the HTML element works well for typical website deployments. +- **[React component](./react.md):** + 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. + +## 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/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) + - [Fitbit Plus OpenAPI Definition](https://raw.githubusercontent.com/TwineHealth/TwineDeveloperDocs/master/spec/swagger.yaml) + +For more information on the OpenAPI specification, refer to the [Learning OpenAPI 3](https://redoc.ly/docs/resources/learning-openapi/) +section in the documentation. + +## Live demo online + +If you want to see how ReDoc will render your OpenAPI definition, you can try it out online at https://redocly.github.io/redoc/. + +A version of the Swagger Petstore API is displayed by default. To test it with your own OpenAPI definition, enter the URL for your +definition and select the **TRY IT** button. diff --git a/docs/quickstart/react.md b/docs/quickstart/react.md new file mode 100644 index 00000000..ebc19845 --- /dev/null +++ b/docs/quickstart/react.md @@ -0,0 +1,78 @@ +--- +title: Using the Redoc React component +--- + +# Using the Redoc React component + +## Before you start + +Install the following dependencies required by Redoc if you do not already have them installed: + +- `react` +- `react-dom` +- `mobx` +- `styled-components` +- `core-js` + +If you have npm installed, you can install these dependencies using the following command: + +```js +npm i react react-dom mobx styled-components core-js +``` + +## Step 1 - Import the `RedocStandalone` component + +```js +import { RedocStandalone } from 'redoc'; +``` + +## Step 2 - Use the component + +You can either link to your OpenAPI definition with a URL, using the following format: + +```react + +``` + +Or you can pass your OpenAPI definition as an object, using the following format: + +```js + +``` + +## Optional - Pass options + +Options can be passed into the RedocStandalone component to alter how it renders. + +For example: + +```js + +``` + +For more information on configuration options, refer to the +[Configuration options for Reference docs](https://redoc.ly/docs/api-reference-docs/configuration/) +section of the documentation. Options available for Redoc are noted, +"Supported in Redoc CE". + +## Optional - Specify `onLoaded` callback + +You can also specify the `onLoaded` callback, which is called each time Redoc +is fully rendered or when an error occurs (with an error as the first argument). + +```js + { + if (!error) { + console.log('Yay!'); + } + }} +/> +```