mirror of
https://github.com/Redocly/redoc.git
synced 2024-11-10 19:06:34 +03:00
sync: Synced local 'docs/' with remote 'docs/redoc/'
This commit is contained in:
parent
6cbd96a24a
commit
bf6b85d4ba
112
docs/quickstart/cli.md
Normal file
112
docs/quickstart/cli.md
Normal file
|
@ -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
|
||||
<!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
|
||||
```
|
39
docs/quickstart/docker.md
Normal file
39
docs/quickstart/docker.md
Normal file
|
@ -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.
|
214
docs/quickstart/html.md
Normal file
214
docs/quickstart/html.md
Normal file
|
@ -0,0 +1,214 @@
|
|||
---
|
||||
title: Using the Redoc HTML element
|
||||
---
|
||||
|
||||
# Using the Redoc HTML element
|
||||
|
||||
## TL;DR final code example
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Redoc</title>
|
||||
<!-- needed for adaptive design -->
|
||||
<meta charset="utf-8"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
|
||||
|
||||
<!--
|
||||
Redoc doesn't change outer page styles
|
||||
-->
|
||||
<style>
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
|
||||
<script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
```
|
||||
|
||||
:::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
|
||||
<script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
|
||||
```
|
||||
|
||||
### Node modules link
|
||||
|
||||
To reference the Redoc script with a node modules link:
|
||||
|
||||
```html
|
||||
<script src="node_modules/redoc/bundles/redoc.standalone.js"> </script>
|
||||
```
|
||||
|
||||
## Step 3 - Add the <redoc> element
|
||||
|
||||
You can add the <redoc> 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 <redoc> element with the `spec-url` attribute:
|
||||
|
||||
```html
|
||||
<redoc spec-url="url/to/your/spec"></redoc>
|
||||
```
|
||||
|
||||
#### Examples
|
||||
|
||||
```html
|
||||
<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
|
||||
```
|
||||
|
||||
You can also use a local file (JSON or YAML) in your project, for instance:
|
||||
|
||||
```html
|
||||
<redoc spec-url="dist.json"></redoc>
|
||||
```
|
||||
|
||||
### Using a Redoc object
|
||||
|
||||
To add the <redoc> 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
|
||||
<script>
|
||||
Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
|
||||
scrollYOffset: 50
|
||||
}, document.getElementById('redoc-container'))
|
||||
</script>
|
||||
```
|
||||
|
||||
You can also use a local file (JSON or YAML) in your project, for instance:
|
||||
|
||||
```html
|
||||
<script>
|
||||
Redoc.init('dist.yaml', {
|
||||
scrollYOffset: 50
|
||||
}, document.getElementById('redoc-container'))
|
||||
</script>
|
||||
```
|
44
docs/quickstart/intro.md
Normal file
44
docs/quickstart/intro.md
Normal file
|
@ -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.
|
78
docs/quickstart/react.md
Normal file
78
docs/quickstart/react.md
Normal file
|
@ -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
|
||||
<RedocStandalone specUrl="url/to/your/spec"/>
|
||||
```
|
||||
|
||||
Or you can pass your OpenAPI definition as an object, using the following format:
|
||||
|
||||
```js
|
||||
<RedocStandalone spec={/* spec as an object */}/>
|
||||
```
|
||||
|
||||
## Optional - Pass options
|
||||
|
||||
Options can be passed into the RedocStandalone component to alter how it renders.
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
<RedocStandalone
|
||||
specUrl="http://petstore.swagger.io/v2/swagger.json"
|
||||
options={{
|
||||
nativeScrollbars: true,
|
||||
theme: { colors: { primary: { main: '#dd5522' } } },
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
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
|
||||
<RedocStandalone
|
||||
specUrl="http://petstore.swagger.io/v2/swagger.json"
|
||||
onLoaded={error => {
|
||||
if (!error) {
|
||||
console.log('Yay!');
|
||||
}
|
||||
}}
|
||||
/>
|
||||
```
|
Loading…
Reference in New Issue
Block a user