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

Updates quickstart with review comments

Browse Source
This commit is contained in:
Heather Cloward 2021-08-15 22:22:04 -04:00
parent 1fff462367
commit e6d001b3c9
6 changed files with 226 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
docs/quickstart/docker.md Normal file
View File

@ -0,0 +1,37 @@
---
title: Using a 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/).
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
```
You can also create a Dockerfile with some redefined environment variables. Check out
a sample [Dockerfile](https://github.com/Redocly/redoc/blob/master/config/docker/Dockerfile)
in our code repo.

94
docs/quickstart/html.md
View File

@ -2,22 +2,22 @@
title: Redoc HTML element title: Redoc HTML element
--- ---
# ReDoc HTML element # Using the Redoc HTML element
## TL;DR Final code example ## TL;DR final code example
```html ```html
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
<title>ReDoc</title> <title>Redoc</title>
<!-- needed for adaptive design --> <!-- needed for adaptive design -->
<meta charset="utf-8"/> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"> <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"> <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 Redoc doesn't change outer page styles
--> -->
<style> <style>
body { body {
@ -28,31 +28,57 @@ title: Redoc HTML element
</head> </head>
<body> <body>
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc> <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> <script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
</body> </body>
</html> </html>
``` ```
:::attention Running Redoc locally requires an HTTP server :::attention Running Redoc locally requires an HTTP server
Loading local OpenAPI specifications is impossible without running a web-server because of issues with 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 [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) and
other security reasons. other security reasons.
::: :::
### Running ReDoc locally ### 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 sever 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`.
If you want to view your ReDoc output locally, you can simulate an HTTP server.
#### Using Python #### Using Python
If you have [Python3](https://www.python.org/downloads/) installed, `cd` into your If you have [Python 3](https://www.python.org/downloads/) installed, `cd` into your
project directory and run the following command: project directory and run the following command:
```python ```python
python3 -m http.server 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 where the preview can be accessed.
To exit the preview, use `control-C`.
#### Using Node.js #### Using Node.js
If you have [Node.js](https://nodejs.org/en/download/) installed, install `http-server` If you have [Node.js](https://nodejs.org/en/download/) installed, install `http-server`
@ -68,10 +94,15 @@ Then, `cd` into your project directory and run the following command:
http-server http-server
``` ```
## Step 1 - Install ReDoc The output after entering the command provides the local where the preview can be accessed.
To exit the preview, use `control-C`.
You can install ReDoc using one of the following package managers, ## Step 1 - Install Redoc
[npm](https://docs.npmjs.com/about-npm) or [yarn](https://classic.yarnpkg.com/en/docs/getting-started).
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 :::attention Initialize your package manager
If you do not have a `package.json` file in your project directory, If you do not have a `package.json` file in your project directory,
@ -83,34 +114,33 @@ For more information, see
[Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file) [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 npm documentation or [Yarn init](https://classic.yarnpkg.com/en/docs/cli/init/)
in the yarn documentation. in the yarn documentation.
::: :::
### Install with yarn ### Install Redoc with yarn
To install ReDoc using yarn, after navigating to your project directory in your terminal, After navigating to your project directory in your terminal, use the following command:
use the following command:
```sh ```sh
yarn add redoc yarn add redoc
``` ```
### Install with npm ### Install Redoc with npm
To install ReDoc using npm, after navigating to your project directory in your terminal, After navigating to your project directory in your terminal, use the following command:
use the following command:
```sh ```sh
npm i redoc npm i redoc
``` ```
## Step 2 - Reference the ReDoc script ## Step 2 - Reference the Redoc script
You can reference the ReDoc script using either a link to the files hosted on a CDN 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. or the files located in your `node modules` folder.
### CDN link ### CDN link
To reference the ReDoc script with a CDN link: To reference the Redoc script with a CDN link:
```html ```html
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
@ -118,7 +148,7 @@ To reference the ReDoc script with a CDN link:
### Node modules link ### Node modules link
To reference the ReDoc script with a node modules link: To reference the Redoc script with a node modules link:
```html ```html
<script src="node_modules/redoc/bundles/redoc.standalone.js"> </script> <script src="node_modules/redoc/bundles/redoc.standalone.js"> </script>
@ -126,11 +156,11 @@ To reference the ReDoc script with a node modules link:
## Step 3 - Add the <redoc> element ## Step 3 - Add the <redoc> element
You can add the <redoc> element to your html page and reference your OpenAPI You can add the <redoc> element to your HTML page and reference your OpenAPI
specification using a `spec-url` attribute, or you can initialize ReDoc using specification using the `spec-url` attribute, or you can initialize Redoc using
a globally exposed ReDoc object. a globally exposed Redoc object.
### Using a `spec-url` attribute ### Using the `spec-url` attribute
To add the <redoc> element with a `spec-url` attribute: To add the <redoc> element with a `spec-url` attribute:
@ -150,9 +180,9 @@ You can also use a local file (JSON or YAML) in your project, for instance:
<redoc spec-url="dist.json"></redoc> <redoc spec-url="dist.json"></redoc>
``` ```
### Using a ReDoc object ### Using a Redoc object
To add the <redoc> element with a globally exposed ReDoc object: To add the <redoc> element with a globally exposed Redoc object:
```js ```js
Redoc.init(specOrSpecUrl, options, element, callback) Redoc.init(specOrSpecUrl, options, element, callback)
@ -160,9 +190,9 @@ Redoc.init(specOrSpecUrl, options, element, callback)
- `specOrSpecUrl`: Either a JSON object with OpenAPI specification or a URL to the - `specOrSpecUrl`: Either a JSON object with OpenAPI specification or a URL to the
specification in JSON or YAML format. specification in JSON or YAML format.
- `options`: See [options object](https://redoc.ly/docs/api-reference-docs/configuration/) reference. - `options`: See [options object](https://redoc.ly/docs/api-reference-docs/configuration/) reference.
- `element`: DOM element ReDoc will be inserted into. - `element`: DOM element Redoc will be inserted into.
- `callback`(optional): Callback to be called after ReDoc has been fully rendered. - `callback`(optional): Callback to be called after Redoc has been fully rendered.
It is also called on errors with error as the first argument. It is also called on errors with `error` as the first argument.
#### Examples #### Examples

42
docs/quickstart/intro.md Normal file
View File

@ -0,0 +1,42 @@
---
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 different options include using the following:
- **[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.
- **[React component](/redoc/quickstart/react.md):**
Using a 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.
## 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 Specification](https://raw.githubusercontent.com/Rebilly/api-definitions/master/openapi/users.yaml)
- [Swagger Petstore Sample OpenAPI Specification](https://petstore3.swagger.io/api/v3/openapi.json)
- OpenAPI 2.0
- [Thingful OpenAPI Specification](https://raw.githubusercontent.com/thingful/openapi-spec/master/spec/swagger.yaml)
- [Fitbit Plus OpenAPI Specification](https://raw.githubusercontent.com/TwineHealth/TwineDeveloperDocs/master/spec/swagger.yaml)
For more information on OpenAPI specifications, 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 already displayed. To test it with your own OpenAPI definition, enter the URL for your
definition and select the **TRY IT** button.

23
docs/quickstart/live-demo.md
View File

@ -1,23 +0,0 @@
---
title: Live demo
enableToc: false
---
# Before you start
You will need an OpenAPI specification. For testing purposes, you can use one of the following sample OpenAPI specifications:
- OpenAPI 3.0
- [Rebilly Users OpenAPI Specification](https://raw.githubusercontent.com/Rebilly/api-definitions/master/openapi/users.yaml)
- [Swagger Petstore Sample OpenAPI Specification](https://petstore3.swagger.io/api/v3/openapi.json)
- OpenAPI 2.0
- [Thingful OpenAPI Specification](https://raw.githubusercontent.com/thingful/openapi-spec/master/spec/swagger.yaml)
- [Fitbit Plus OpenAPI Specification](https://raw.githubusercontent.com/TwineHealth/TwineDeveloperDocs/master/spec/swagger.yaml)
For more information on OpenAPI specifications see [Learning OpenAPI 3](https://redoc.ly/docs/resources/learning-openapi/).
## Live demo online
If you want to see how ReDoc will render your OpenAPI specification, you can try it out online at https://redocly.github.io/redoc/.
A version of the Swagger Petstore API is already displayed. Try with your own OpenAPI specification by
entering the URL for your specification and clicking the **TRY IT** button.

78
docs/quickstart/react.md Normal file
View File

@ -0,0 +1,78 @@
---
title: 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!');
}
}}
/>
```

11
docs/sidebars.yaml
View File

@ -1,8 +1,11 @@
redoc: redoc:
- group: Quickstart - group: Quickstart
expanded: false expanded: false
page: redoc/quickstart/intro.md
pages: pages:
- label: Live demo - label: HTML element
page: redoc/quickstart/live-demo.md page: redoc/quickstart/html.md
- label: ReDoc HTML element - label: React component
page: redoc/quickstart/html.md page: redoc/quickstart/react.md
- label: Docker image
page: redoc/quickstart/docker.md