mirror of
https://github.com/Redocly/redoc.git
synced 2024-11-22 08:36:33 +03:00
[GSoD]Reorganizes the quickstart into a deployment guide and quickstart (#1749)
* Reorganizes the quickstart into a deployment guide and quickstart * Minor edits * fix: minor formatting issue * fix: simplify phrasing * Adds redirects, link to preview-docs docs, and other review edits * remove IE polyfills as IE is no longer supported Co-authored-by: Ivana Isadora Devcic <33730345+skadinna@users.noreply.github.com>
This commit is contained in:
Heather Cloward
GitHub
parent
262177ddfd
commit
6cbd96a24a
|
|
@ -183,6 +183,7 @@ IE support for Redoc.
|
|||
For more information on Redoc's commmand-line interface, refer to
|
||||
[**Using the Redoc CLI**](https://redoc.ly/docs/redoc/quickstart/cli/).
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
### Security Definition location
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
---
|
||||
title: Using the Redoc CLI
|
||||
redirectFrom:
|
||||
- /docs/quickstart/cli/
|
||||
---
|
||||
|
||||
# Using the Redoc CLI
|
||||
|
|
@ -1,5 +1,7 @@
|
|||
---
|
||||
title: Using the Redoc Docker image
|
||||
redirectFrom:
|
||||
- /docs/quickstart/docker/
|
||||
---
|
||||
|
||||
# Using the Redoc Docker image
|
||||
|
|
@ -1,101 +1,11 @@
|
|||
---
|
||||
title: Using the Redoc HTML element
|
||||
redirectFrom:
|
||||
- /docs/quickstart/html/
|
||||
---
|
||||
|
||||
# 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 +23,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
|
||||
115
docs/deployment/intro.md
Normal file
115
docs/deployment/intro.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
title: Redoc deployment guide
|
||||
redirectFrom:
|
||||
- /docs/quickstart/intro/
|
||||
---
|
||||
|
||||
# Redoc deployment guide
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
::: openapi.yaml
|
||||
Replace `openapi.yaml` in the example command with the file path to your OpenAPI definition.
|
||||
:::
|
||||
|
||||
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`.
|
||||
|
||||
You can alter the port if you are using 8080 already, for example:
|
||||
|
||||
```bash
|
||||
openapi preview-docs -p 8888 openapi.yaml
|
||||
```
|
||||
|
||||
::: openapi.yaml
|
||||
Replace `openapi.yaml` in the example command with the file path to your OpenAPI definition.
|
||||
:::
|
||||
|
||||
For more information about the `preview-docs` command, refer to
|
||||
[OpenAPI CLI commands](https://redoc.ly/docs/cli/commands/preview-docs/#preview-docs) in the OpenAPI CLI documentation.
|
||||
|
||||
#### 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`.
|
||||
|
|
@ -1,5 +1,7 @@
|
|||
---
|
||||
title: Using the Redoc React component
|
||||
redirectFrom:
|
||||
- /docs/quickstart/react/
|
||||
---
|
||||
|
||||
# Using the Redoc React component
|
||||
51
docs/quickstart.md
Normal file
51
docs/quickstart.md
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
title: Redoc quickstart guide
|
||||
---
|
||||
|
||||
# Redoc quickstart guide
|
||||
|
||||
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](https://redoc.ly/docs/deployment/intro/#running_redoc_locally) for
|
||||
more information.
|
||||
:::
|
||||
|
||||
For a more detailed explanation with step-by-step instructions and additional options for using Redoc, 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