-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[GSoD]Reorganizes the quickstart into a deployment guide and quicksta…
…rt (#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>
- Loading branch information
1 parent
262177d
commit 6cbd96a
Showing
9 changed files
with
183 additions
and
143 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,7 @@ | ||
--- | ||
title: Using the Redoc CLI | ||
redirectFrom: | ||
- /docs/quickstart/cli/ | ||
--- | ||
|
||
# Using the Redoc CLI | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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://github.com/raw/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://github.com/raw/thingful/openapi-spec/master/spec/swagger.yaml) | ||
- [Fitbit Plus OpenAPI Definition](https://github.com/raw/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`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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). |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |