mirror of
https://github.com/Redocly/redoc.git
synced 2025-08-06 05:10:20 +03:00
Reorganizes the quickstart into a deployment guide and quickstart
This commit is contained in:
Heather Cloward
parent
1d088a8dd8
commit
db4c7fdfde
10
README.md
10
README.md
|
|
@ -18,12 +18,12 @@
|
|||
[<img alt="Deploy to Github" src="http://i.imgur.com/YZmaqk3.png" height="60px">](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) [<img alt="ReDoc as a service" src="http://i.imgur.com/edqdCv6.png" height="60px">](https://redoc.ly) [<img alt="Customization services" src="http://i.imgur.com/c4sUF7M.png" height="60px">](https://redoc.ly/#services)
|
||||
|
||||
## Features
|
||||
- [Multiple deployment options](https://redoc.ly/docs/redoc/quickstart/intro/)
|
||||
- [Server-side rendering (SSR) ready](https://redoc.ly/docs/redoc/quickstart/cli/#redoc-cli-commands)
|
||||
- [Simple integration with `create-react-app`](https://redoc.ly/docs/redoc/quickstart/react/)
|
||||
- [Multiple deployment options](https://redoc.ly/docs/redoc/deployment/intro/)
|
||||
- [Server-side rendering (SSR) ready](https://redoc.ly/docs/redoc/deployment/cli/#redoc-cli-commands)
|
||||
- [Simple integration with `create-react-app`](https://redoc.ly/docs/redoc/deployment/react/)
|
||||
|
||||
[See an example](https://github.com/APIs-guru/create-react-app-redoc)
|
||||
- [Command-line interface to bundle your docs into a **zero-dependency** HTML file](https://redoc.ly/docs/redoc/quickstart/cli/)
|
||||
- [Command-line interface to bundle your docs into a **zero-dependency** HTML file](https://redoc.ly/docs/redoc/deployment/cli/)
|
||||
- Responsive three-panel design with menu/scrolling synchronization
|
||||
- Deep linking support
|
||||
- Ability to integrate your API introduction into the side menu
|
||||
|
|
@ -75,7 +75,7 @@ to render your OpenAPI definition, refer to the
|
|||
|
||||
## ReDoc CLI
|
||||
For more information on Redoc's commmand-line interface, refer to
|
||||
[Using the Redoc CLI](https://redoc.ly/docs/redoc/quickstart/cli/).
|
||||
[Using the Redoc CLI](https://redoc.ly/docs/redoc/quickstart).
|
||||
|
||||
## Configuration
|
||||
|
||||
|
|
|
|||
|
|
@ -4,98 +4,6 @@ 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:
|
||||
|
|
@ -113,7 +21,6 @@ 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
|
||||
99
docs/deployment/intro.md
Normal file
99
docs/deployment/intro.md
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
---
|
||||
title: Redoc deployment guide
|
||||
---
|
||||
|
||||
# Redoc deployment 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.
|
||||
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 **TRY IT**.
|
||||
- **[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
|
||||
|
||||
### OpenAPI definition
|
||||
|
||||
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)
|
||||
|
||||
::: OpenAPI Specification info
|
||||
For more information on the OpenAPI specification, refer to the [Learning OpenAPI 3](https://redoc.ly/docs/resources/learning-openapi/)
|
||||
section in the documentation.
|
||||
:::
|
||||
|
||||
### 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`.
|
||||
|
|
@ -26,6 +26,25 @@ npm i react react-dom mobx styled-components core-js
|
|||
import { RedocStandalone } from 'redoc';
|
||||
```
|
||||
|
||||
### IE polyfills
|
||||
|
||||
If you use Redoc as a React component and you want your OpenAPI definition to render with
|
||||
IE browsers, include the following polyfills in your project:
|
||||
|
||||
```
|
||||
import 'core-js/es6/promise';
|
||||
import 'core-js/fn/array/find';
|
||||
import 'core-js/fn/object/assign';
|
||||
import 'core-js/fn/string/ends-with';
|
||||
import 'core-js/fn/string/starts-with';
|
||||
|
||||
import 'core-js/es6/map';
|
||||
import 'core-js/es6/symbol';
|
||||
|
||||
import 'unfetch/polyfill/index'; // or any other fetch polyfill
|
||||
import 'url-polyfill';
|
||||
```
|
||||
|
||||
## Step 2 - Use the component
|
||||
|
||||
You can either link to your OpenAPI definition with a URL, using the following format:
|
||||
52
docs/quickstart.md
Normal file
52
docs/quickstart.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
title: Redoc quickstart guide
|
||||
---
|
||||
|
||||
# TL;DR final code example
|
||||
|
||||
To render your OpenAPI definition using Redoc, use the following HTML code sample and
|
||||
replace the `spec-url` attribute with the url or local file address to your definition.
|
||||
|
||||
```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 element with link to your OpenAPI definition
|
||||
-->
|
||||
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
|
||||
<!--
|
||||
Link to Redoc JavaScript on CDN for rendering standalone element
|
||||
-->
|
||||
<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. Refer to [Running Redoc locally](/deployment/intro/#running_redoc_locally) for
|
||||
more information.
|
||||
:::
|
||||
|
||||
For a more detailed explanation with step-by-step instructions and additional options for using Redoc to render
|
||||
your OpenAPI definition, refer to the [Redoc deployment guide](/deployment/intro)
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -1,13 +1,15 @@
|
|||
redoc:
|
||||
- group: Quickstart
|
||||
- label: Quickstart
|
||||
- page: redoc/quickstart.md
|
||||
- group: Deployment
|
||||
expanded: false
|
||||
page: redoc/quickstart/intro.md
|
||||
page: redoc/deployment/intro.md
|
||||
pages:
|
||||
- label: HTML element
|
||||
page: redoc/quickstart/html.md
|
||||
page: redoc/deployment/html.md
|
||||
- label: React component
|
||||
page: redoc/quickstart/react.md
|
||||
page: redoc/deployment/react.md
|
||||
- label: Docker image
|
||||
page: redoc/quickstart/docker.md
|
||||
page: redoc/deployment/docker.md
|
||||
- label: Command-line interface
|
||||
page: redoc/quickstart/cli.md
|
||||
page: redoc/deployment/cli.md
|
||||
Loading…
Reference in New Issue
Block a user