sync: Synced local 'docs/' with remote 'docs/redoc/'

Ernel1997 · Nov 23, 2021 · bf6b85d · bf6b85d
1 parent 6cbd96a
commit bf6b85d
Show file tree

Hide file tree

Showing 5 changed files with 487 additions and 0 deletions.
diff --git a/docs/quickstart/cli.md b/docs/quickstart/cli.md
@@ -0,0 +1,112 @@
+---
+title: Using the Redoc CLI
+---
+
+# Using the Redoc CLI
+
+With Redoc's command-line interface you can bundle your OpenAPI definition and API documentation
+(made with Redoc) into a zero-dependency HTML file and locally render your
+OpenAPI definition with Redoc.
+
+## Step 1 - Install Redoc CLI
+
+You can install the `redoc-cli` package globally using one of the following package managers:
+
+- [npm](https://docs.npmjs.com/about-npm)
+- [yarn](https://classic.yarnpkg.com/en/docs/getting-started)
+
+Or you can install `redoc-cli` using [npx](https://www.freecodecamp.org/news/npm-vs-npx-whats-the-difference/).
+
+### Install Redoc CLI with yarn
+
+To install the `redoc-cli` package globally with yarn: 
+
+```bash
+yarn global add redoc-cli
+```
+
+### Install Redoc with npm
+
+To install the `redoc-cli` package globally with npm: 
+
+```bash
+npm i -g redoc-cli
+```
+
+### Install with `npx`
+
+To install the `redoc-cli` package locally with `npx`, navigate to your project
+directory in your terminal, then use the following command:
+
+```bash
+npx redoc-cli
+```
+
+## Step 2 - Use the CLI
+
+### Redoc CLI commands
+
+The CLI includes the following commands:
+
+- **`redoc-cli serve [spec]`:** Starts a local server with Redoc. You must include the required parameter, spec, which is
+  a reference to an OpenAPI definition. Options include:
+    - `--ssr`: Implements a server-side rendering model. 
+    - `--watch`: Automatically reloads the server while you edit your OpenAPI definition.
+    - `--options`: Customizes your output using [Redoc options](https://redoc.ly/docs/api-reference-docs/configuration/).
+      To add nested options, use dot notation.
+- **`redoc-cli bundle [spec]`:** Bundles `spec` and Redoc into a zero-dependency HTML file. Options include:
+    - `-t` or `--template`: Uses custom [Handlebars](https://handlebarsjs.com/) templates to render your OpenAPI definition.
+    - `--templateOptions`: Adds template options you want to pass to your
+      custom Handlebars template. To add options, use dot notation.
+- **`--help`:** Prints help text for the Redoc CLI commands and options.
+- **`--version`:** Prints the version of the `redoc-cli` package you have installed.
+
+### Redoc CLI examples
+
+#### Bundle
+
+Bundle with the main color changed to `orange`:
+
+```bash
+redoc-cli bundle openapi.yaml --options.theme.colors.primary.main=orange
+```
+
+Bundle using a custom Handlebars template and add custom `templateOptions`:
+
+```bash
+redoc-cli bundle http://petstore.swagger.io/v2/swagger.json -t custom.hbs --templateOptions.metaDescription "Page meta description"
+```
+
+Sample Handlebars template:
+
+```handlebars
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="utf8" />
+        <title>{{title}}</title>
+        <!-- needed for adaptive design -->
+        <meta description="{{{templateOptions.metaDescription}}}">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <style>
+            body {
+            padding: 0;
+            margin: 0;
+            }
+        </style>
+        {{{redocHead}}}
+        {{#unless disableGoogleFont}}<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">{{/unless}}
+    </head>
+    <body>
+      {{{redocHTML}}}
+    </body>
+</html>
+```
+
+#### Serve
+
+Serve with the `nativeScrollbars` option set to `true`:
+
+```bash
+redoc-cli serve  openapi/dist.yaml --options.nativeScrollbars
+```
diff --git a/docs/quickstart/docker.md b/docs/quickstart/docker.md
@@ -0,0 +1,39 @@
+---
+title: Using the Redoc Docker image
+---
+
+# Using the Redoc Docker image
+
+Redoc is available as a pre-built Docker image in [Docker Hub](https://hub.docker.com/r/redocly/redoc/).
+
+If you have [Docker](https://docs.docker.com/get-docker/) installed, pull the image with the following command:
+
+```docker
+docker pull redocly/redoc
+```
+
+Then run the image with the following command:
+
+```docker
+docker run -p 8080:80 redocly/redoc
+```
+
+The preview starts on port 8080, based on the port used in the command,
+and can be accessed at `http://localhost:8080`.
+To exit the preview, use `control+C`.
+
+By default Redoc starts with a demo Swagger Petstore OpenAPI definition located at
+http://petstore.swagger.io/v2/swagger.json. You can update this URL using
+the environment variable `SPEC_URL`. 
+
+For example:
+
+```bash
+docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc
+```
+
+## Using a Dockerfile
+
+You can also create a Dockerfile with some predefined environment variables. Check out
+a sample [Dockerfile](https://github.com/Redocly/redoc/blob/master/config/docker/Dockerfile)
+in our code repo.
diff --git a/docs/quickstart/html.md b/docs/quickstart/html.md
@@ -0,0 +1,214 @@
+---
+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:
+
+- [npm](https://docs.npmjs.com/about-npm)
+- [yarn](https://classic.yarnpkg.com/en/docs/getting-started)
+
+:::attention Initialize your package manager
+If you do not have a `package.json` file in your project directory,
+you need to add one by initializing npm or yarn in your project. Use the command `npm init` for npm,
+or `yarn init` for yarn. These initialization commands will lead you through the process
+of creating a `package.json` file in your project. 
+
+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
+
+After navigating to your project directory in your terminal, use the following command: 
+
+```bash
+yarn add redoc
+```
+
+### Install Redoc with npm
+
+After navigating to your project directory in your terminal, use the following command: 
+
+```bash
+npm i redoc
+```
+
+## Step 2 - Reference the Redoc script
+
+You can reference the Redoc script using either a link to the files hosted on a CDN
+or the files located in your `node modules` folder.
+
+### CDN link
+
+To reference the Redoc script with a CDN link:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
+```
+
+### Node modules link
+
+To reference the Redoc script with a node modules link:
+
+```html
+<script src="node_modules/redoc/bundles/redoc.standalone.js"> </script>
+```
+
+## Step 3 - Add the <redoc> element
+
+You can add the <redoc> element to your HTML page and reference your OpenAPI
+definition using the `spec-url` attribute, or you can initialize Redoc using
+a globally exposed Redoc object.
+
+### Using the `spec-url` attribute
+
+To add the <redoc> element with the `spec-url` attribute:
+
+```html
+<redoc spec-url="url/to/your/spec"></redoc>
+```
+
+#### Examples
+
+```html
+<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
+```
+
+You can also use a local file (JSON or YAML) in your project, for instance:
+
+```html
+<redoc spec-url="dist.json"></redoc>
+```
+
+### Using a Redoc object
+
+To add the <redoc> element with a globally exposed Redoc object:
+
+```js
+Redoc.init(specOrSpecUrl, options, element, callback)
+```
+- `specOrSpecUrl`: Either a JSON object with the OpenAPI definition or a URL to the
+  definition in JSON or YAML format.
+- `options`: See [options object](https://redoc.ly/docs/api-reference-docs/configuration/) reference.
+- `element`: DOM element Redoc will be inserted into.
+- `callback`(optional): Callback to be called after Redoc has been fully rendered.
+  It is also called on errors with `error` as the first argument.
+
+#### Examples
+
+```html
+<script>
+Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
+  scrollYOffset: 50
+}, document.getElementById('redoc-container'))
+</script>
+```
+
+You can also use a local file (JSON or YAML) in your project, for instance:
+
+```html
+<script>
+Redoc.init('dist.yaml', {
+  scrollYOffset: 50
+}, document.getElementById('redoc-container'))
+</script>
+```