diff --git a/README.md b/README.md index 855dac49..63e50ffb 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,12 @@ [Deploy to Github](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) [ReDoc as a service](https://redoc.ly) [Customization services](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 diff --git a/docs/quickstart/cli.md b/docs/deployment/cli.md similarity index 100% rename from docs/quickstart/cli.md rename to docs/deployment/cli.md diff --git a/docs/quickstart/docker.md b/docs/deployment/docker.md similarity index 100% rename from docs/quickstart/docker.md rename to docs/deployment/docker.md 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 bfc8d267..486d4048 100644 --- a/docs/quickstart/html.md +++ b/docs/deployment/html.md @@ -4,98 +4,6 @@ title: Using the Redoc HTML element # 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 +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 diff --git a/docs/deployment/intro.md b/docs/deployment/intro.md new file mode 100644 index 00000000..1428d0fd --- /dev/null +++ b/docs/deployment/intro.md @@ -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`. diff --git a/docs/quickstart/react.md b/docs/deployment/react.md similarity index 78% rename from docs/quickstart/react.md rename to docs/deployment/react.md index ebc19845..4b410d21 100644 --- a/docs/quickstart/react.md +++ b/docs/deployment/react.md @@ -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: diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 00000000..0c4d2e57 --- /dev/null +++ b/docs/quickstart.md @@ -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 + + + + 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](/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) \ No newline at end of file diff --git a/docs/quickstart/intro.md b/docs/quickstart/intro.md deleted file mode 100644 index e23f9d00..00000000 --- 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://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. diff --git a/docs/sidebars.yaml b/docs/sidebars.yaml index 2189f25b..c4f7b0e6 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