mirror of
https://github.com/Redocly/redoc.git
synced 2025-08-06 05:10:20 +03:00
Updates quickstart with review comments
This commit is contained in:
Heather Cloward
parent
1fff462367
commit
e6d001b3c9
37
docs/quickstart/docker.md
Normal file
37
docs/quickstart/docker.md
Normal 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.
|
||||
|
|
@ -2,22 +2,22 @@
|
|||
title: Redoc HTML element
|
||||
---
|
||||
|
||||
# ReDoc HTML element
|
||||
# Using the Redoc HTML element
|
||||
|
||||
## TL;DR Final code example
|
||||
## TL;DR final code example
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>ReDoc</title>
|
||||
<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
|
||||
Redoc doesn't change outer page styles
|
||||
-->
|
||||
<style>
|
||||
body {
|
||||
|
|
@ -28,31 +28,57 @@ title: Redoc HTML element
|
|||
</head>
|
||||
<body>
|
||||
<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>
|
||||
</html>
|
||||
|
||||
```
|
||||
|
||||
:::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
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
```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 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`
|
||||
|
|
@ -68,10 +94,15 @@ Then, `cd` into your project directory and run the following command:
|
|||
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,
|
||||
[npm](https://docs.npmjs.com/about-npm) or [yarn](https://classic.yarnpkg.com/en/docs/getting-started).
|
||||
## 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,
|
||||
|
|
@ -83,34 +114,33 @@ 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 with yarn
|
||||
### Install Redoc with yarn
|
||||
|
||||
To install ReDoc using yarn, after navigating to your project directory in your terminal,
|
||||
use the following command:
|
||||
After navigating to your project directory in your terminal, use the following command:
|
||||
|
||||
```sh
|
||||
yarn add redoc
|
||||
```
|
||||
|
||||
### Install with npm
|
||||
### Install Redoc with npm
|
||||
|
||||
To install ReDoc using npm, after navigating to your project directory in your terminal,
|
||||
use the following command:
|
||||
After navigating to your project directory in your terminal, use the following command:
|
||||
|
||||
```sh
|
||||
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
|
||||
or the files located in your node modules folder.
|
||||
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:
|
||||
To reference the Redoc script with a CDN link:
|
||||
|
||||
```html
|
||||
<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
|
||||
|
||||
To reference the ReDoc script with a node modules link:
|
||||
To reference the Redoc script with a node modules link:
|
||||
|
||||
```html
|
||||
<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
|
||||
|
||||
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
|
||||
a globally exposed ReDoc object.
|
||||
You can add the <redoc> element to your HTML page and reference your OpenAPI
|
||||
specification using the `spec-url` attribute, or you can initialize Redoc using
|
||||
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:
|
||||
|
||||
|
|
@ -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>
|
||||
```
|
||||
|
||||
### 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
|
||||
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
|
||||
specification 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.
|
||||
- `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
|
||||
|
||||
|
|
|
|||
42
docs/quickstart/intro.md
Normal file
42
docs/quickstart/intro.md
Normal 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.
|
||||
|
|
@ -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
78
docs/quickstart/react.md
Normal 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!');
|
||||
}
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
|
@ -1,8 +1,11 @@
|
|||
redoc:
|
||||
- group: Quickstart
|
||||
expanded: false
|
||||
page: redoc/quickstart/intro.md
|
||||
pages:
|
||||
- label: Live demo
|
||||
page: redoc/quickstart/live-demo.md
|
||||
- label: ReDoc HTML element
|
||||
page: redoc/quickstart/html.md
|
||||
- label: HTML element
|
||||
page: redoc/quickstart/html.md
|
||||
- label: React component
|
||||
page: redoc/quickstart/react.md
|
||||
- label: Docker image
|
||||
page: redoc/quickstart/docker.md
|
||||
Loading…
Reference in New Issue
Block a user