From 7b2931dc91e6bfefb909d12d512aeb1d0df29a19 Mon Sep 17 00:00:00 2001 From: redocly-bot Date: Thu, 9 Nov 2023 15:56:30 +0000 Subject: [PATCH] sync: Synced local 'docs/' with remote 'docs/redoc/' --- docs/config.md | 2 +- docs/deployment/html.md | 2 +- docs/index.md | 4 +- docs/redoc-vendor-extensions.md | 212 +++++++++++++------------ docs/security-definitions-injection.md | 4 +- 5 files changed, 114 insertions(+), 110 deletions(-) diff --git a/docs/config.md b/docs/config.md index 36880135..b034ed6e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -8,7 +8,7 @@ Each deployment type has documentation on how to configure options for that type :::success Client-side configuration -Using Redoc as a standalone (HTML or React) tool, these options must be presented in [kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). +Using Redoc as a standalone (HTML or React) tool, these options must be presented in [kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`. ::: diff --git a/docs/deployment/html.md b/docs/deployment/html.md index fab2169c..23b914b2 100644 --- a/docs/deployment/html.md +++ b/docs/deployment/html.md @@ -126,7 +126,7 @@ The main example shows using the CDN: If you would instead prefer to host the depdencies yourself, first install `redoc` using `npm`: -``` +```sh npm install redoc ``` diff --git a/docs/index.md b/docs/index.md index 58613ee6..a98776c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,7 +28,7 @@ Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, If you have Node installed, quickly generate documentation using `npx`: -``` +```sh npx @redocly/cli build-docs openapi.yaml ``` @@ -84,7 +84,7 @@ theme: Redocly CLI detects a file named `redocly.yaml` in the same directory as you run the command and uses it. See the documentation with a command like this: -``` +```sh redocly preview-docs openapi.yaml ``` diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index d6280adc..5074cff3 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.md @@ -3,78 +3,79 @@ You can use the following [vendor extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/) with Redoc. - [Redoc vendor extensions](#redoc-vendor-extensions) - - [Swagger Object](#swagger-object) - - [x-servers](#x-servers) - - [x-tagGroups](#x-taggroups) - - [How to use with Redoc](#how-to-use-with-redoc) - - [Tag Group Object](#tag-group-object) - - [Fixed fields](#fixed-fields) - - [x-tagGroups example](#x-taggroups-example) - - [x-ignoredHeaderParameters](#x-ignoredheaderparameters) - - [How to use with Redoc](#how-to-use-with-redoc-1) - - [x-ignoredHeaderParameters example](#x-ignoredheaderparameters-example) - - [Info Object](#info-object) - - [x-logo](#x-logo) - - [How to use with Redoc](#how-to-use-with-redoc-2) - - [Logo Object](#logo-object) - - [Fixed fields](#fixed-fields-1) - - [x-logo example](#x-logo-example) - - [Tag Object](#tag-object) - - [x-traitTag](#x-traittag) - - [How to use with Redoc](#how-to-use-with-redoc-3) - - [x-traitTag example](#x-traittag-example) - - [x-displayName](#x-displayname) - - [Operation Object vendor extensions](#operation-object-vendor-extensions) - - [x-codeSamples](#x-codesamples) - - [How to use with Redoc](#how-to-use-with-redoc-4) - - [Code Sample Object](#code-sample-object) - - [Fixed fields](#fixed-fields-2) - - [Code Sample Object example](#code-sample-object-example) - - [Parameter Object](#parameter-object) - - [x-examples](#x-examples) - - [How to use with Redoc](#how-to-use-with-redoc-5) - - [Response Object vendor extensions](#response-object-vendor-extensions) - - [x-summary](#x-summary) - - [How to use with Redoc](#how-to-use-with-redoc-6) - - [Schema Object](#schema-object) - - [x-nullable](#x-nullable) - - [How to use with Redoc](#how-to-use-with-redoc-7) - - [x-extendedDiscriminator](#x-extendeddiscriminator) - - [How to use with Redoc](#how-to-use-with-redoc-8) - - [x-extendedDiscriminator example](#x-extendeddiscriminator-example) - - [x-additionalPropertiesName](#x-additionalpropertiesname) - - [How to use with Redoc](#how-to-use-with-redoc-9) - - [x-additionalPropertiesName example](#x-additionalpropertiesname-example) - - [x-explicitMappingOnly](#x-explicitmappingonly) - - [How to use with Redoc](#how-to-use-with-redoc-10) - - [x-explicitMappingOnly example](#x-explicitmappingonly-example) + - [Swagger Object](#swagger-object) + - [x-servers](#x-servers) + - [x-tagGroups](#x-taggroups) + - [How to use with Redoc](#how-to-use-with-redoc) + - [Tag Group Object](#tag-group-object) + - [Fixed fields](#fixed-fields) + - [x-tagGroups example](#x-taggroups-example) + - [x-ignoredHeaderParameters](#x-ignoredheaderparameters) + - [How to use with Redoc](#how-to-use-with-redoc-1) + - [x-ignoredHeaderParameters example](#x-ignoredheaderparameters-example) + - [Info Object](#info-object) + - [x-logo](#x-logo) + - [How to use with Redoc](#how-to-use-with-redoc-2) + - [Logo Object](#logo-object) + - [Fixed fields](#fixed-fields-1) + - [x-logo example](#x-logo-example) + - [Tag Object](#tag-object) + - [x-traitTag](#x-traittag) + - [How to use with Redoc](#how-to-use-with-redoc-3) + - [x-traitTag example](#x-traittag-example) + - [x-displayName](#x-displayname) + - [Operation Object vendor extensions](#operation-object-vendor-extensions) + - [x-codeSamples](#x-codesamples) + - [How to use with Redoc](#how-to-use-with-redoc-4) + - [Code Sample Object](#code-sample-object) + - [Fixed fields](#fixed-fields-2) + - [Code Sample Object example](#code-sample-object-example) + - [Parameter Object](#parameter-object) + - [x-examples](#x-examples) + - [How to use with Redoc](#how-to-use-with-redoc-5) + - [Response Object vendor extensions](#response-object-vendor-extensions) + - [x-summary](#x-summary) + - [How to use with Redoc](#how-to-use-with-redoc-6) + - [Schema Object](#schema-object) + - [x-nullable](#x-nullable) + - [How to use with Redoc](#how-to-use-with-redoc-7) + - [x-extendedDiscriminator](#x-extendeddiscriminator) + - [How to use with Redoc](#how-to-use-with-redoc-8) + - [x-extendedDiscriminator example](#x-extendeddiscriminator-example) + - [x-additionalPropertiesName](#x-additionalpropertiesname) + - [How to use with Redoc](#how-to-use-with-redoc-9) + - [x-additionalPropertiesName example](#x-additionalpropertiesname-example) + - [x-explicitMappingOnly](#x-explicitmappingonly) + - [How to use with Redoc](#how-to-use-with-redoc-10) + - [x-explicitMappingOnly example](#x-explicitmappingonly-example) -### Swagger Object +## Swagger Object Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi/) -#### x-servers +### x-servers Backported from OpenAPI 3.0 [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject). Currently doesn't support templates. -#### x-tagGroups +### x-tagGroups -| Field Name | Type | Description | +| Field Name | Type | Description | | :------------- | :-----------: | :---------- | | x-tagGroups | [ [Tag Group Object](#tag-group-object) ] | A list of tag groups | -###### How to use with Redoc +#### How to use with Redoc `x-tagGroups` is used to group tags in the side menu. Before you use `x-tagGroups`, make sure you **add all tags to a group**, since a tag that is not in a group, **is not displayed** at all! + #### Tag Group Object Information about tags group -###### Fixed fields -| Field Name | Type | Description | +##### Fixed fields +| Field Name | Type | Description | | :---------- | :--------: | :---------- | | name | string | The group name | | tags | [ string ] | List of tags to include in this group -###### x-tagGroups example +#### x-tagGroups example json ```json { @@ -104,18 +105,18 @@ x-tagGroups: - Secondary Stats ``` -#### x-ignoredHeaderParameters +### x-ignoredHeaderParameters -| Field Name | Type | Description | +| Field Name | Type | Description | | :-------------------------- | :-----------: | :---------- | | x-ignoredHeaderParameters | [ string ] | A list of ignored headers | -###### How to use with Redoc +#### How to use with Redoc Use `x-ignoredHeaderParameters` to specify header parameter names which are ignored by Redoc. -###### x-ignoredHeaderParameters example +#### x-ignoredHeaderParameters example ```yaml swagger: '2.0' info: @@ -127,23 +128,25 @@ x-ignoredHeaderParameters: - X-Test-Header ``` -### Info Object +## Info Object Extends the OpenAPI [Info Object](https://redocly.com/docs/openapi-visual-reference/info/) -#### x-logo -| Field Name | Type | Description | +### x-logo + +| Field Name | Type | Description | | :------------- | :-----------: | :---------- | | x-logo | [Logo Object](#logo-object) | The information about API logo | -###### How to use with Redoc +#### How to use with Redoc `x-logo` is used to specify API logo. The corresponding image is displayed just above the side-menu. + #### Logo Object The information about API logo -###### Fixed fields -| Field Name | Type | Description | +#### Fixed fields +| Field Name | Type | Description | | :-------------- | :------: | :---------- | | url | string | The URL pointing to the spec logo. MUST be in the format of a URL. It SHOULD be an absolute URL so your API definition is usable from any location | backgroundColor | string | background color to be used. MUST be RGB color in [hexadecimal format] (https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) @@ -151,7 +154,7 @@ The information about API logo | href | string | The URL pointing to the contact page. Default to 'info.contact.url' field of the OAS. -###### x-logo example +#### x-logo example json ```json { @@ -177,19 +180,19 @@ info: altText: "Petstore logo" ``` -### Tag Object +## Tag Object Extends the OpenAPI [Tag Object](https://redocly.com/docs/openapi-visual-reference/tags/) -#### x-traitTag -| Field Name | Type | Description | +### x-traitTag +| Field Name | Type | Description | | :------------- | :------: | :---------- | | x-traitTag | boolean | In Swagger two operations can have multiple tags. This property distinguishes between tags that are used to group operations (default) from tags that are used to mark operation with certain trait (`true` value) | -###### How to use with Redoc +#### How to use with Redoc Tags that have `x-traitTag` set to `true` are listed in the side-menu but don't have any subitems (operations). It also renders the `description` tag. This is useful for handling out common things like Pagination, Rate-Limits, etc. -###### x-traitTag example +#### x-traitTag example json ```json { @@ -205,36 +208,37 @@ description: Pagination description (can use markdown syntax) x-traitTag: true ``` -#### x-displayName +### x-displayName -| Field Name | Type | Description | +| Field Name | Type | Description | | :------------- | :------: | :---------- | | x-displayName | string | Defines the text that is used for this tag in the menu and in section headings | -### Operation Object vendor extensions +## Operation Object vendor extensions Extends the OpenAPI [Operation Object](https://redocly.com/docs/openapi-visual-reference/operation/) -#### x-codeSamples -| Field Name | Type | Description | +### x-codeSamples +| Field Name | Type | Description | | :------------- | :------: | :---------- | | x-codeSamples | [ [Code Sample Object](#code-sample-object) ] | 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. -#### Code Sample Object + +### Code Sample Object Operation code sample -###### Fixed fields -| Field Name | Type | Description | +#### Fixed fields +| Field Name | Type | Description | | :---------- | :------: | :----------- | | lang | string | Code sample language. Value should be one of the following [list](https://github.com/github/linguist/blob/master/lib/linguist/popular.yml) | | label | string? | Code sample label, for example `Node` or `Python2.7`, _optional_, `lang` is used by default | | source | string | Code sample source code | -###### Code Sample Object example +#### Code Sample Object example json ```json { @@ -248,53 +252,53 @@ lang: JavaScript source: console.log('Hello World'); ``` -### Parameter Object +## Parameter Object Extends the OpenAPI [Parameter Object](https://redocly.com/docs/openapi-visual-reference/parameter/) -#### x-examples +### x-examples | Field Name | Type | Description | | :------------- | :------: | :---------- | | x-examples | [Example Object](https://redocly.com/docs/openapi-visual-reference/example/) | 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. -### Response Object vendor extensions +## Response Object vendor extensions Extends the OpenAPI [Response Object](https://redocly.com/docs/openapi-visual-reference/response/). -#### x-summary -| Field Name | Type | Description | +### x-summary +| Field Name | Type | Description | | :------------- | :------: | :---------- | | 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 +## Schema Object Extends the OpenAPI [Schema Object](https://redocly.com/docs/openapi-visual-reference/schemas/) -#### x-nullable -| Field Name | Type | Description | +### x-nullable +| Field Name | Type | Description | | :------------- | :------: | :---------- | | 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. -#### x-extendedDiscriminator +### x-extendedDiscriminator **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 | -###### How to use with Redoc +#### 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 is used as an 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`. -###### x-extendedDiscriminator example +#### x-extendedDiscriminator example ```yaml @@ -334,19 +338,19 @@ 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. +### x-additionalPropertiesName +**Attention**: This is a Redoc-specific vendor extension, and is not supported by other tools. Extends the `additionalProperties` property of the schema object. -| Field Name | Type | Description | +| Field Name | Type | Description | | :------------- | :------: | :---------- | | 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`. -###### x-additionalPropertiesName example +#### x-additionalPropertiesName example ```yaml Player: @@ -362,20 +366,20 @@ Player: type: string ``` -#### x-explicitMappingOnly -**ATTENTION**: This is Redoc-specific vendor extension, and is not supported by other tools. +### x-explicitMappingOnly +**Attention**: This is Redoc-specific vendor extension, and is not supported by other tools. Extends the `discriminator` property of the schema object. -| Field Name | Type | Description | +| Field Name | Type | Description | | :------------- | :------: | :---------- | | 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. When set to `true`, the selectpicker lists only the explicitly defined mappings. When `false`, the default behavior is kept, in other words, explicit and implicit mappings are shown. -###### x-explicitMappingOnly example +#### x-explicitMappingOnly example ```yaml diff --git a/docs/security-definitions-injection.md b/docs/security-definitions-injection.md index ded59881..dbe3d6b6 100644 --- a/docs/security-definitions-injection.md +++ b/docs/security-definitions-injection.md @@ -4,7 +4,7 @@ You can inject the Security Definitions widget anywhere in your specification `d ```markdown ... -# Authorization +## Authorization Some description @@ -14,7 +14,7 @@ Some description The inject instruction is wrapped in an HTML comment, so it is **visible only in Redoc** and not visible, for instance, in the SwaggerUI. -# Default behavior +## Default behavior If the injection tag is not found in the description, it is appended to the end of description under the `Authentication` header.