From ab02f667a1c0c3226ee6b87024a7c23e04577134 Mon Sep 17 00:00:00 2001 From: redocly-bot Date: Wed, 9 Feb 2022 12:18:16 +0000 Subject: [PATCH] sync: Synced local 'docs/' with remote 'docs/redoc/' --- docs/deployment/cli.md | 12 +++++------ docs/deployment/docker.md | 10 ++++----- docs/deployment/html.md | 18 ++++++++-------- docs/deployment/intro.md | 8 +++---- docs/deployment/react.md | 8 +++---- docs/quickstart.md | 7 +++--- docs/redoc-vendor-extensions.md | 38 ++++++++++++++++----------------- 7 files changed, 51 insertions(+), 50 deletions(-) diff --git a/docs/deployment/cli.md b/docs/deployment/cli.md index 8bfc9e2c..092d50fa 100644 --- a/docs/deployment/cli.md +++ b/docs/deployment/cli.md @@ -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. diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index a8c3c9b8..4ec791c0 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -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. \ No newline at end of file +in our code repo. diff --git a/docs/deployment/html.md b/docs/deployment/html.md index 872d05ac..52a59c83 100644 --- a/docs/deployment/html.md +++ b/docs/deployment/html.md @@ -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 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 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: ``` -### Using a Redoc object +### The Redoc object To add the element with a globally exposed Redoc object: @@ -120,4 +120,4 @@ Redoc.init('dist.yaml', { scrollYOffset: 50 }, document.getElementById('redoc-container')) -``` \ No newline at end of file +``` diff --git a/docs/deployment/intro.md b/docs/deployment/intro.md index 43eea451..5b03a762 100644 --- a/docs/deployment/intro.md +++ b/docs/deployment/intro.md @@ -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: diff --git a/docs/deployment/react.md b/docs/deployment/react.md index 84050c3c..d290b023 100644 --- a/docs/deployment/react.md +++ b/docs/deployment/react.md @@ -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". diff --git a/docs/quickstart.md b/docs/quickstart.md index 2dba080d..7607c10f 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -43,11 +43,12 @@ replace the `spec-url` attribute with the URL or local file address to your defi ``` -:::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). diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 884dfb70..62b83853 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.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. @@ -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. #### 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