mirror of
https://github.com/Redocly/redoc.git
synced 2025-07-12 17:22:29 +03:00
sync: Synced local 'docs/' with remote 'docs/redoc/'
This commit is contained in:
parent
57cdd9f6da
commit
ab02f667a1
|
@ -1,10 +1,10 @@
|
||||||
---
|
---
|
||||||
title: Using the Redoc CLI
|
title: Use the Redoc CLI
|
||||||
redirectFrom:
|
redirectFrom:
|
||||||
- /docs/quickstart/cli/
|
- /docs/quickstart/cli/
|
||||||
---
|
---
|
||||||
|
|
||||||
# Using the Redoc CLI
|
# How to use the Redoc CLI
|
||||||
|
|
||||||
With Redoc's command-line interface you can bundle your OpenAPI definition and API documentation
|
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
|
(made with Redoc) into a zero-dependency HTML file and locally render your
|
||||||
|
@ -21,7 +21,7 @@ Or you can install `redoc-cli` using [npx](https://www.freecodecamp.org/news/npm
|
||||||
|
|
||||||
### Install Redoc CLI with yarn
|
### Install Redoc CLI with yarn
|
||||||
|
|
||||||
To install the `redoc-cli` package globally with yarn:
|
To install the `redoc-cli` package globally with yarn:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
yarn global add redoc-cli
|
yarn global add redoc-cli
|
||||||
|
@ -29,7 +29,7 @@ yarn global add redoc-cli
|
||||||
|
|
||||||
### Install Redoc with npm
|
### Install Redoc with npm
|
||||||
|
|
||||||
To install the `redoc-cli` package globally with npm:
|
To install the `redoc-cli` package globally with npm:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm i -g redoc-cli
|
npm i -g redoc-cli
|
||||||
|
@ -52,7 +52,7 @@ 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
|
- **`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:
|
a reference to an OpenAPI definition. Options include:
|
||||||
- `--ssr`: Implements a server-side rendering model.
|
- `--ssr`: Implements a server-side rendering model.
|
||||||
- `--watch`: Automatically reloads the server while you edit your OpenAPI definition.
|
- `--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/).
|
- `--options`: Customizes your output using [Redoc options](https://redoc.ly/docs/api-reference-docs/configuration/).
|
||||||
To add nested options, use dot notation.
|
To add nested options, use dot notation.
|
||||||
|
|
|
@ -1,10 +1,10 @@
|
||||||
---
|
---
|
||||||
title: Using the Redoc Docker image
|
title: Use the Redoc Docker image
|
||||||
redirectFrom:
|
redirectFrom:
|
||||||
- /docs/quickstart/docker/
|
- /docs/quickstart/docker/
|
||||||
---
|
---
|
||||||
|
|
||||||
# Using the Redoc Docker image
|
# How to use the Redoc Docker image
|
||||||
|
|
||||||
Redoc is available as a pre-built Docker image in [Docker Hub](https://hub.docker.com/r/redocly/redoc/).
|
Redoc is available as a pre-built Docker image in [Docker Hub](https://hub.docker.com/r/redocly/redoc/).
|
||||||
|
|
||||||
|
@ -26,7 +26,7 @@ To exit the preview, use `control+C`.
|
||||||
|
|
||||||
By default Redoc starts with a demo Swagger Petstore OpenAPI definition located at
|
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
|
http://petstore.swagger.io/v2/swagger.json. You can update this URL using
|
||||||
the environment variable `SPEC_URL`.
|
the environment variable `SPEC_URL`.
|
||||||
|
|
||||||
For example:
|
For example:
|
||||||
|
|
||||||
|
@ -34,8 +34,8 @@ For example:
|
||||||
docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc
|
docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc
|
||||||
```
|
```
|
||||||
|
|
||||||
## Using a Dockerfile
|
## Create a Dockerfile
|
||||||
|
|
||||||
You can also create a Dockerfile with some predefined environment variables. Check out
|
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)
|
a sample [Dockerfile](https://github.com/Redocly/redoc/blob/master/config/docker/Dockerfile)
|
||||||
in our code repo.
|
in our code repo.
|
||||||
|
|
|
@ -1,10 +1,10 @@
|
||||||
---
|
---
|
||||||
title: Using the Redoc HTML element
|
title: Use the Redoc HTML element
|
||||||
redirectFrom:
|
redirectFrom:
|
||||||
- /docs/quickstart/html/
|
- /docs/quickstart/html/
|
||||||
---
|
---
|
||||||
|
|
||||||
# Using the Redoc HTML element
|
# How to use the Redoc HTML element
|
||||||
|
|
||||||
## Step 1 - Install Redoc
|
## Step 1 - Install Redoc
|
||||||
|
|
||||||
|
@ -17,9 +17,9 @@ You can install Redoc using one of the following package managers:
|
||||||
If you do not have a `package.json` file in your project directory,
|
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,
|
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
|
or `yarn init` for yarn. These initialization commands will lead you through the process
|
||||||
of creating a `package.json` file in your project.
|
of creating a `package.json` file in your project.
|
||||||
|
|
||||||
For more information, see
|
For more information, see
|
||||||
[Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file)
|
[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 npm documentation or [Yarn init](https://classic.yarnpkg.com/en/docs/cli/init/)
|
||||||
in the yarn documentation.
|
in the yarn documentation.
|
||||||
|
@ -27,7 +27,7 @@ in the yarn documentation.
|
||||||
|
|
||||||
### Install Redoc with yarn
|
### Install Redoc with yarn
|
||||||
|
|
||||||
After navigating to your project directory in your terminal, use the following command:
|
After navigating to your project directory in your terminal, use the following command:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
yarn add redoc
|
yarn add redoc
|
||||||
|
@ -35,7 +35,7 @@ yarn add redoc
|
||||||
|
|
||||||
### Install Redoc with npm
|
### Install Redoc with npm
|
||||||
|
|
||||||
After navigating to your project directory in your terminal, use the following command:
|
After navigating to your project directory in your terminal, use the following command:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm i redoc
|
npm i redoc
|
||||||
|
@ -68,7 +68,7 @@ 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
|
definition using the `spec-url` attribute, or you can initialize Redoc using
|
||||||
a globally exposed Redoc object.
|
a globally exposed Redoc object.
|
||||||
|
|
||||||
### Using the `spec-url` attribute
|
### The `spec-url` attribute
|
||||||
|
|
||||||
To add the <redoc> element with the `spec-url` attribute:
|
To add the <redoc> element with the `spec-url` attribute:
|
||||||
|
|
||||||
|
@ -88,7 +88,7 @@ You can also use a local file (JSON or YAML) in your project, for instance:
|
||||||
<redoc spec-url="dist.json"></redoc>
|
<redoc spec-url="dist.json"></redoc>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Using a Redoc object
|
### The Redoc object
|
||||||
|
|
||||||
To add the <redoc> element with a globally exposed Redoc object:
|
To add the <redoc> element with a globally exposed Redoc object:
|
||||||
|
|
||||||
|
@ -120,4 +120,4 @@ Redoc.init('dist.yaml', {
|
||||||
scrollYOffset: 50
|
scrollYOffset: 50
|
||||||
}, document.getElementById('redoc-container'))
|
}, document.getElementById('redoc-container'))
|
||||||
</script>
|
</script>
|
||||||
```
|
```
|
||||||
|
|
|
@ -42,11 +42,11 @@ For more information on the OpenAPI specification, refer to the [Learning OpenAP
|
||||||
section in the documentation.
|
section in the documentation.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
### Running Redoc locally
|
### How to run Redoc locally
|
||||||
|
|
||||||
If you want to view your Redoc output locally, you can simulate an HTTP server.
|
If you want to view your Redoc output locally, you can simulate an HTTP server.
|
||||||
|
|
||||||
#### Using Redocly OpenAPI CLI
|
#### Redocly OpenAPI CLI
|
||||||
|
|
||||||
Redocly OpenAPI CLI is an open source command-line tool that includes a command
|
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.
|
for simulating an HTTP server to provide a preview of your OpenAPI definition locally.
|
||||||
|
@ -74,7 +74,7 @@ Replace `openapi.yaml` in the example command with the file path to your OpenAPI
|
||||||
For more information about the `preview-docs` command, refer to
|
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.
|
[OpenAPI CLI commands](https://redoc.ly/docs/cli/commands/preview-docs/#preview-docs) in the OpenAPI CLI documentation.
|
||||||
|
|
||||||
#### Using Python
|
#### Python
|
||||||
|
|
||||||
If you have [Python 3](https://www.python.org/downloads/) installed, `cd` into your
|
If you have [Python 3](https://www.python.org/downloads/) installed, `cd` into your
|
||||||
project directory and run the following command:
|
project directory and run the following command:
|
||||||
|
@ -93,7 +93,7 @@ python -m SimpleHTTPServer 8000
|
||||||
The output after entering the command provides the local URL where the preview can be accessed.
|
The output after entering the command provides the local URL where the preview can be accessed.
|
||||||
To exit the preview, use `control-C`.
|
To exit the preview, use `control-C`.
|
||||||
|
|
||||||
#### Using Node.js
|
#### Node.js
|
||||||
|
|
||||||
If you have [Node.js](https://nodejs.org/en/download/) installed, install `http-server`
|
If you have [Node.js](https://nodejs.org/en/download/) installed, install `http-server`
|
||||||
using the following npm command:
|
using the following npm command:
|
||||||
|
|
|
@ -1,10 +1,10 @@
|
||||||
---
|
---
|
||||||
title: Using the Redoc React component
|
title: Use the Redoc React component
|
||||||
redirectFrom:
|
redirectFrom:
|
||||||
- /docs/quickstart/react/
|
- /docs/quickstart/react/
|
||||||
---
|
---
|
||||||
|
|
||||||
# Using the Redoc React component
|
# How to use the Redoc React component
|
||||||
|
|
||||||
## Before you start
|
## Before you start
|
||||||
|
|
||||||
|
@ -44,7 +44,7 @@ Or you can pass your OpenAPI definition as an object, using the following format
|
||||||
|
|
||||||
## Optional - Pass options
|
## Optional - Pass options
|
||||||
|
|
||||||
Options can be passed into the RedocStandalone component to alter how it renders.
|
Options can be passed into the RedocStandalone component to alter how it renders.
|
||||||
|
|
||||||
For example:
|
For example:
|
||||||
|
|
||||||
|
@ -58,7 +58,7 @@ For example:
|
||||||
/>
|
/>
|
||||||
```
|
```
|
||||||
|
|
||||||
For more information on configuration options, refer to the
|
For more information on configuration options, refer to the
|
||||||
[Configuration options for Reference docs](https://redoc.ly/docs/api-reference-docs/configuration/)
|
[Configuration options for Reference docs](https://redoc.ly/docs/api-reference-docs/configuration/)
|
||||||
section of the documentation. Options available for Redoc are noted,
|
section of the documentation. Options available for Redoc are noted,
|
||||||
"Supported in Redoc CE".
|
"Supported in Redoc CE".
|
||||||
|
|
|
@ -43,11 +43,12 @@ replace the `spec-url` attribute with the URL or local file address to your defi
|
||||||
</html>
|
</html>
|
||||||
```
|
```
|
||||||
|
|
||||||
:::attention Running Redoc locally requires an HTTP server
|
:::attention Redoc requires an HTTP server to run locally
|
||||||
|
|
||||||
Loading local OpenAPI definitions is impossible without running a web server because of issues with
|
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
|
[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.md#running-redoc-locally) for
|
other security reasons. Refer to [Running Redoc locally](./deployment/intro.md#how-to-run-redoc-locally) for more information.
|
||||||
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.md).
|
For a more detailed explanation with step-by-step instructions and additional options for using Redoc, refer to the [Redoc deployment guide](./deployment/intro.md).
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# ReDoc vendor extensions
|
# Redoc vendor extensions
|
||||||
|
|
||||||
You can use the following [vendor extensions](https://swagger.io/specification/#specificationExtensions) with Redoc.
|
You can use the following [vendor extensions](https://swagger.io/specification/#specificationExtensions) with Redoc.
|
||||||
|
|
||||||
|
@ -194,8 +194,8 @@ Extends the OpenAPI [Operation Object](http://swagger.io/specification/#operatio
|
||||||
| :------------- | :------: | :---------- |
|
| :------------- | :------: | :---------- |
|
||||||
| x-codeSamples | [ [Code Sample Object](#codeSampleObject) ] | A list of code samples associated with operation |
|
| x-codeSamples | [ [Code Sample Object](#codeSampleObject) ] | A list of code samples associated with operation |
|
||||||
|
|
||||||
###### How to use with ReDoc
|
###### How to use with Redoc
|
||||||
`x-codeSamples` are rendered on the right panel in ReDoc.
|
`x-codeSamples` are rendered on the right panel in Redoc.
|
||||||
|
|
||||||
#### <a name="codeSampleObject"></a>Code Sample Object
|
#### <a name="codeSampleObject"></a>Code Sample Object
|
||||||
Operation code sample
|
Operation code sample
|
||||||
|
@ -230,8 +230,8 @@ Extends the OpenAPI [Parameter Object](http://swagger.io/specification/#paramete
|
||||||
| :------------- | :------: | :---------- |
|
| :------------- | :------: | :---------- |
|
||||||
| x-examples | [Example Object](http://swagger.io/specification/#exampleObject) | Object that contains examples for the request. Applies when `in` is `body` and mime-type is `application/json` |
|
| x-examples | [Example Object](http://swagger.io/specification/#exampleObject) | Object that contains examples for the request. Applies when `in` is `body` and mime-type is `application/json` |
|
||||||
|
|
||||||
###### How to use with ReDoc
|
###### How to use with Redoc
|
||||||
`x-examples` are rendered in the JSON tab on the right panel in ReDoc.
|
`x-examples` are rendered in the JSON tab on the right panel in Redoc.
|
||||||
|
|
||||||
### Response Object vendor extensions
|
### Response Object vendor extensions
|
||||||
Extends the OpenAPI [Response Object](https://swagger.io/specification/#responseObject)
|
Extends the OpenAPI [Response Object](https://swagger.io/specification/#responseObject)
|
||||||
|
@ -241,7 +241,7 @@ Extends the OpenAPI [Response Object](https://swagger.io/specification/#response
|
||||||
| :------------- | :------: | :---------- |
|
| :------------- | :------: | :---------- |
|
||||||
| x-summary | string | a short summary of the response |
|
| x-summary | string | a short summary of the response |
|
||||||
|
|
||||||
###### How to use with ReDoc
|
###### How to use with Redoc
|
||||||
If specified, you can use `x-summary` as the response button text, with description rendered under the button.
|
If specified, you can use `x-summary` as the response button text, with description rendered under the button.
|
||||||
|
|
||||||
### Schema Object
|
### Schema Object
|
||||||
|
@ -252,21 +252,21 @@ Extends the OpenAPI [Schema Object](http://swagger.io/specification/#schemaObjec
|
||||||
| :------------- | :------: | :---------- |
|
| :------------- | :------: | :---------- |
|
||||||
| x-nullable | boolean | marks schema as a nullable |
|
| x-nullable | boolean | marks schema as a nullable |
|
||||||
|
|
||||||
###### How to use with ReDoc
|
###### How to use with Redoc
|
||||||
Schemas marked as `x-nullable` are marked in ReDoc with the label Nullable
|
Schemas marked as `x-nullable` are marked in Redoc with the label Nullable
|
||||||
|
|
||||||
#### x-extendedDiscriminator
|
#### x-extendedDiscriminator
|
||||||
**ATTENTION**: This is a ReDoc-specific vendor extension, and is not supported by other tools.
|
**ATTENTION**: This is a Redoc-specific vendor extension, and is not supported by other tools.
|
||||||
|
|
||||||
| Field Name | Type | Description |
|
| Field Name | Type | Description |
|
||||||
| :------------- | :------: | :---------- |
|
| :------------- | :------: | :---------- |
|
||||||
| x-extendedDiscriminator | string | specifies extended discriminator |
|
| x-extendedDiscriminator | string | specifies extended discriminator |
|
||||||
|
|
||||||
###### How to use with ReDoc
|
###### How to use with Redoc
|
||||||
ReDoc uses this vendor extension to solve name-clash issues with the standard `discriminator`.
|
Redoc uses this vendor extension to solve name-clash issues with the standard `discriminator`.
|
||||||
Value of this field specifies the field which will be used as a extended discriminator.
|
Value of this field specifies the field which will be used as a extended discriminator.
|
||||||
ReDoc displays definition with selectpicker using which user can select value of the `x-extendedDiscriminator`-marked field.
|
Redoc displays definition with selectpicker using which user can select value of the `x-extendedDiscriminator`-marked field.
|
||||||
ReDoc displays the definition derived from the current (using `allOf`) and has `enum` with only one value which is the same as the selected value of the field specified as `x-extendedDiscriminator`.
|
Redoc displays the definition derived from the current (using `allOf`) and has `enum` with only one value which is the same as the selected value of the field specified as `x-extendedDiscriminator`.
|
||||||
|
|
||||||
###### x-extendedDiscriminator example
|
###### x-extendedDiscriminator example
|
||||||
|
|
||||||
|
@ -309,7 +309,7 @@ PayPalPayment:
|
||||||
In the example above, the names of definitions (`PayPalPayment`) are named differently than names in the payload (`paypal`) which is not supported by default `discriminator`.
|
In the example above, the names of definitions (`PayPalPayment`) are named differently than names in the payload (`paypal`) which is not supported by default `discriminator`.
|
||||||
|
|
||||||
#### x-additionalPropertiesName
|
#### x-additionalPropertiesName
|
||||||
**ATTENTION**: This is a ReDoc-specific vendor extension, and is not supported by other tools.
|
**ATTENTION**: This is a Redoc-specific vendor extension, and is not supported by other tools.
|
||||||
|
|
||||||
Extends the `additionalProperties` property of the schema object.
|
Extends the `additionalProperties` property of the schema object.
|
||||||
|
|
||||||
|
@ -317,8 +317,8 @@ Extends the `additionalProperties` property of the schema object.
|
||||||
| :------------- | :------: | :---------- |
|
| :------------- | :------: | :---------- |
|
||||||
| x-additionalPropertiesName | string | descriptive name of additional properties keys |
|
| x-additionalPropertiesName | string | descriptive name of additional properties keys |
|
||||||
|
|
||||||
###### How to use with ReDoc
|
###### How to use with Redoc
|
||||||
ReDoc uses this extension to display a more descriptive property name in objects with `additionalProperties` when viewing the property list with an `object`.
|
Redoc uses this extension to display a more descriptive property name in objects with `additionalProperties` when viewing the property list with an `object`.
|
||||||
|
|
||||||
###### x-additionalPropertiesName example
|
###### x-additionalPropertiesName example
|
||||||
|
|
||||||
|
@ -337,7 +337,7 @@ Player:
|
||||||
```
|
```
|
||||||
|
|
||||||
#### x-explicitMappingOnly
|
#### x-explicitMappingOnly
|
||||||
**ATTENTION**: This is ReDoc-specific vendor extension, and is not supported by other tools.
|
**ATTENTION**: This is Redoc-specific vendor extension, and is not supported by other tools.
|
||||||
|
|
||||||
Extends the `discriminator` property of the schema object.
|
Extends the `discriminator` property of the schema object.
|
||||||
|
|
||||||
|
@ -345,8 +345,8 @@ Extends the `discriminator` property of the schema object.
|
||||||
| :------------- | :------: | :---------- |
|
| :------------- | :------: | :---------- |
|
||||||
| x-explicitMappingOnly | boolean | limit the discriminator selectpicker to the explicit mappings only |
|
| x-explicitMappingOnly | boolean | limit the discriminator selectpicker to the explicit mappings only |
|
||||||
|
|
||||||
###### How to use with ReDoc
|
###### How to use with Redoc
|
||||||
ReDoc uses this extension to filter the `discriminator` mappings shown in the selectpicker.
|
Redoc uses this extension to filter the `discriminator` mappings shown in the selectpicker.
|
||||||
When set to `true`, the selectpicker will only list the the explicitly defined mappings. When `false`, the default behavior is kept, i.e. explicit and implicit mappings will be shown.
|
When set to `true`, the selectpicker will only list the the explicitly defined mappings. When `false`, the default behavior is kept, i.e. explicit and implicit mappings will be shown.
|
||||||
|
|
||||||
###### x-explicitMappingOnly example
|
###### x-explicitMappingOnly example
|
||||||
|
|
Loading…
Reference in New Issue
Block a user