From 6cbd96a24ad3c731ae8802e1048d69cf0d6a67e5 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Tue, 23 Nov 2021 00:07:56 -0500 Subject: [PATCH] [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> --- README.md | 1 + docs/{quickstart => deployment}/cli.md | 2 + docs/{quickstart => deployment}/docker.md | 2 + docs/{quickstart => deployment}/html.md | 95 +----------------- docs/deployment/intro.md | 115 ++++++++++++++++++++++ docs/{quickstart => deployment}/react.md | 2 + docs/quickstart.md | 51 ++++++++++ docs/quickstart/intro.md | 44 --------- docs/sidebars.yaml | 14 +-- 9 files changed, 183 insertions(+), 143 deletions(-) rename docs/{quickstart => deployment}/cli.md (98%) rename docs/{quickstart => deployment}/docker.md (96%) rename docs/{quickstart => deployment}/html.md (55%) create mode 100644 docs/deployment/intro.md rename docs/{quickstart => deployment}/react.md (97%) create mode 100644 docs/quickstart.md delete mode 100644 docs/quickstart/intro.md diff --git a/README.md b/README.md index e8969e941a..4af6ad0eef 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/quickstart/cli.md b/docs/deployment/cli.md similarity index 98% rename from docs/quickstart/cli.md rename to docs/deployment/cli.md index b0f2af85b7..8bfc9e2c5e 100644 --- a/docs/quickstart/cli.md +++ b/docs/deployment/cli.md @@ -1,5 +1,7 @@ --- title: Using the Redoc CLI +redirectFrom: + - /docs/quickstart/cli/ --- # Using the Redoc CLI diff --git a/docs/quickstart/docker.md b/docs/deployment/docker.md similarity index 96% rename from docs/quickstart/docker.md rename to docs/deployment/docker.md index 31539fdbb0..a8c3c9b836 100644 --- a/docs/quickstart/docker.md +++ b/docs/deployment/docker.md @@ -1,5 +1,7 @@ --- title: Using the Redoc Docker image +redirectFrom: + - /docs/quickstart/docker/ --- # Using the Redoc Docker image diff --git a/docs/quickstart/html.md b/docs/deployment/html.md similarity index 55% rename from docs/quickstart/html.md rename to docs/deployment/html.md index bfc8d2678c..872d05ac52 100644 --- a/docs/quickstart/html.md +++ b/docs/deployment/html.md @@ -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 - - - - Redoc - - - - - - - - - - - - - - -``` - -:::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 diff --git a/docs/deployment/intro.md b/docs/deployment/intro.md new file mode 100644 index 0000000000..210e13740a --- /dev/null +++ b/docs/deployment/intro.md @@ -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`. diff --git a/docs/quickstart/react.md b/docs/deployment/react.md similarity index 97% rename from docs/quickstart/react.md rename to docs/deployment/react.md index ebc198459c..84050c3cdc 100644 --- a/docs/quickstart/react.md +++ b/docs/deployment/react.md @@ -1,5 +1,7 @@ --- title: Using the Redoc React component +redirectFrom: + - /docs/quickstart/react/ --- # Using the Redoc React component diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000000..8548c59b42 --- /dev/null +++ b/docs/quickstart.md @@ -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 + + + + Redoc + + + + + + + + + + + + + + + + +``` + +:::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). \ No newline at end of file diff --git a/docs/quickstart/intro.md b/docs/quickstart/intro.md deleted file mode 100644 index e23f9d00b3..0000000000 --- a/docs/quickstart/intro.md +++ /dev/null @@ -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://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) - -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. diff --git a/docs/sidebars.yaml b/docs/sidebars.yaml index 2189f25b0b..c4f7b0e6de 100644 --- a/docs/sidebars.yaml +++ b/docs/sidebars.yaml @@ -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 \ No newline at end of file + page: redoc/deployment/cli.md \ No newline at end of file