Redocly/redoc
1
1
Fork 0
mirror of https://github.com/Redocly/redoc.git synced 2024-11-22 00:26:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
redocly-bot 2022-02-09 12:18:16 +00:00
parent 57cdd9f6da
commit ab02f667a1
7 changed files with 51 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/deployment/cli.md
View File

@ -1,10 +1,10 @@
---
title: Using the Redoc CLI
redirectFrom:
title: Use the Redoc CLI
redirectFrom:
- /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
(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
To install the `redoc-cli` package globally with yarn:
To install the `redoc-cli` package globally with yarn:
```bash
yarn global add redoc-cli
@ -29,7 +29,7 @@ yarn global add redoc-cli
### Install Redoc with npm
To install the `redoc-cli` package globally with npm:
To install the `redoc-cli` package globally with npm:
```bash
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
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.
- `--options`: Customizes your output using [Redoc options](https://redoc.ly/docs/api-reference-docs/configuration/).
To add nested options, use dot notation.

10
docs/deployment/docker.md
View File

@ -1,10 +1,10 @@
---
title: Using the Redoc Docker image
title: Use the Redoc Docker image
redirectFrom:
- /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/).
@ -26,7 +26,7 @@ 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`.
the environment variable `SPEC_URL`.
For example:
@ -34,8 +34,8 @@ For example:
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
a sample [Dockerfile](https://github.com/Redocly/redoc/blob/master/config/docker/Dockerfile)
in our code repo.
in our code repo.

18
docs/deployment/html.md
View File

@ -1,10 +1,10 @@
---
title: Using the Redoc HTML element
title: Use the Redoc HTML element
redirectFrom:
- /docs/quickstart/html/
---
# Using the Redoc HTML element
# How to use the Redoc HTML element
## 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,
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.
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)
in the npm documentation or [Yarn init](https://classic.yarnpkg.com/en/docs/cli/init/)
in the yarn documentation.
@ -27,7 +27,7 @@ in the yarn documentation.
### 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
yarn add redoc
@ -35,7 +35,7 @@ yarn add redoc
### 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
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
a globally exposed Redoc object.
### Using the `spec-url` attribute
### 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>
```
### Using a Redoc object
### The Redoc object
To add the <redoc> element with a globally exposed Redoc object:
@ -120,4 +120,4 @@ Redoc.init('dist.yaml', {
scrollYOffset: 50
}, document.getElementById('redoc-container'))
</script>
```
```

8
docs/deployment/intro.md
View File

@ -42,11 +42,11 @@ For more information on the OpenAPI specification, refer to the [Learning OpenAP
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.
#### Using Redocly OpenAPI CLI
#### 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.
@ -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
[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
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.
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`
using the following npm command:

8
docs/deployment/react.md
View File

@ -1,10 +1,10 @@
---
title: Using the Redoc React component
title: Use the Redoc React component
redirectFrom:
- /docs/quickstart/react/
---
# Using the Redoc React component
# How to use the Redoc React component
## Before you start
@ -44,7 +44,7 @@ Or you can pass your OpenAPI definition as an object, using the following format
## 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:
@ -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/)
section of the documentation. Options available for Redoc are noted,
"Supported in Redoc CE".

7
docs/quickstart.md
View File

@ -43,11 +43,12 @@ replace the `spec-url` attribute with the URL or local file address to your defi
</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
[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
more information.
other security reasons. Refer to [Running Redoc locally](./deployment/intro.md#how-to-run-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.md).

38
docs/redoc-vendor-extensions.md
View File

@ -1,4 +1,4 @@
# ReDoc vendor extensions
# Redoc vendor extensions
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 |
###### How to use with ReDoc
`x-codeSamples` are rendered on the right panel in ReDoc.
###### How to use with Redoc
`x-codeSamples` are rendered on the right panel in Redoc.
#### <a name="codeSampleObject"></a>Code Sample Object
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` |
###### How to use with ReDoc
`x-examples` are rendered in the JSON tab on the right panel in ReDoc.
###### How to use with Redoc
`x-examples` are rendered in the JSON tab on the right panel in Redoc.
### Response Object vendor extensions
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 |
###### 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.
### Schema Object
@ -252,21 +252,21 @@ Extends the OpenAPI [Schema Object](http://swagger.io/specification/#schemaObjec
| :------------- | :------: | :---------- |
| x-nullable | boolean | marks schema as a nullable |
###### How to use with ReDoc
Schemas marked as `x-nullable` are marked in ReDoc with the label Nullable
###### How to use with Redoc
Schemas marked as `x-nullable` are marked in Redoc with the label Nullable
#### 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 |
| :------------- | :------: | :---------- |
| x-extendedDiscriminator | string | specifies extended discriminator |
###### How to use with ReDoc
ReDoc uses this vendor extension to solve name-clash issues with the standard `discriminator`.
###### How to use with Redoc
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.
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 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`.
###### 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`.
#### 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.
@ -317,8 +317,8 @@ Extends the `additionalProperties` property of the schema object.
| :------------- | :------: | :---------- |
| x-additionalPropertiesName | string | descriptive name of additional properties keys |
###### 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`.
###### 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`.
###### x-additionalPropertiesName example
@ -337,7 +337,7 @@ Player:
```
#### 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.
@ -345,8 +345,8 @@ Extends the `discriminator` property of the schema object.
| :------------- | :------: | :---------- |
| x-explicitMappingOnly | boolean | limit the discriminator selectpicker to the explicit mappings only |
###### How to use with ReDoc
ReDoc uses this extension to filter the `discriminator` mappings shown in the selectpicker.
###### How to use with Redoc
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.
###### x-explicitMappingOnly example