Redocly/redoc
1
1
Fork 0
mirror of https://github.com/Redocly/redoc.git synced 2024-11-25 01:53:44 +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 2023-11-09 15:56:30 +00:00
parent b2d8e0f5b7
commit 7b2931dc91
5 changed files with 114 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/deployment/html.md
View File

@ -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`: If you would instead prefer to host the depdencies yourself, first install `redoc` using `npm`:
``` ```sh
npm install redoc npm install redoc
``` ```

4
docs/index.md
View File

@ -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`: If you have Node installed, quickly generate documentation using `npx`:
``` ```sh
npx @redocly/cli build-docs openapi.yaml 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: 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 redocly preview-docs openapi.yaml
``` ```

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

@ -3,78 +3,79 @@
You can use the following [vendor extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/) with Redoc. You can use the following [vendor extensions](https://redocly.com/docs/openapi-visual-reference/specification-extensions/) with Redoc.
- [Redoc vendor extensions](#redoc-vendor-extensions) - [Redoc vendor extensions](#redoc-vendor-extensions)
- [Swagger Object](#swagger-object) - [Swagger Object](#swagger-object)
- [x-servers](#x-servers) - [x-servers](#x-servers)
- [x-tagGroups](#x-taggroups) - [x-tagGroups](#x-taggroups)
- [How to use with Redoc](#how-to-use-with-redoc) - [How to use with Redoc](#how-to-use-with-redoc)
- [Tag Group Object](#tag-group-object) - [Tag Group Object](#tag-group-object)
- [Fixed fields](#fixed-fields) - [Fixed fields](#fixed-fields)
- [x-tagGroups example](#x-taggroups-example) - [x-tagGroups example](#x-taggroups-example)
- [x-ignoredHeaderParameters](#x-ignoredheaderparameters) - [x-ignoredHeaderParameters](#x-ignoredheaderparameters)
- [How to use with Redoc](#how-to-use-with-redoc-1) - [How to use with Redoc](#how-to-use-with-redoc-1)
- [x-ignoredHeaderParameters example](#x-ignoredheaderparameters-example) - [x-ignoredHeaderParameters example](#x-ignoredheaderparameters-example)
- [Info Object](#info-object) - [Info Object](#info-object)
- [x-logo](#x-logo) - [x-logo](#x-logo)
- [How to use with Redoc](#how-to-use-with-redoc-2) - [How to use with Redoc](#how-to-use-with-redoc-2)
- [Logo Object](#logo-object) - [Logo Object](#logo-object)
- [Fixed fields](#fixed-fields-1) - [Fixed fields](#fixed-fields-1)
- [x-logo example](#x-logo-example) - [x-logo example](#x-logo-example)
- [Tag Object](#tag-object) - [Tag Object](#tag-object)
- [x-traitTag](#x-traittag) - [x-traitTag](#x-traittag)
- [How to use with Redoc](#how-to-use-with-redoc-3) - [How to use with Redoc](#how-to-use-with-redoc-3)
- [x-traitTag example](#x-traittag-example) - [x-traitTag example](#x-traittag-example)
- [x-displayName](#x-displayname) - [x-displayName](#x-displayname)
- [Operation Object vendor extensions](#operation-object-vendor-extensions) - [Operation Object vendor extensions](#operation-object-vendor-extensions)
- [x-codeSamples](#x-codesamples) - [x-codeSamples](#x-codesamples)
- [How to use with Redoc](#how-to-use-with-redoc-4) - [How to use with Redoc](#how-to-use-with-redoc-4)
- [Code Sample Object](#code-sample-object) - [Code Sample Object](#code-sample-object)
- [Fixed fields](#fixed-fields-2) - [Fixed fields](#fixed-fields-2)
- [Code Sample Object example](#code-sample-object-example) - [Code Sample Object example](#code-sample-object-example)
- [Parameter Object](#parameter-object) - [Parameter Object](#parameter-object)
- [x-examples](#x-examples) - [x-examples](#x-examples)
- [How to use with Redoc](#how-to-use-with-redoc-5) - [How to use with Redoc](#how-to-use-with-redoc-5)
- [Response Object vendor extensions](#response-object-vendor-extensions) - [Response Object vendor extensions](#response-object-vendor-extensions)
- [x-summary](#x-summary) - [x-summary](#x-summary)
- [How to use with Redoc](#how-to-use-with-redoc-6) - [How to use with Redoc](#how-to-use-with-redoc-6)
- [Schema Object](#schema-object) - [Schema Object](#schema-object)
- [x-nullable](#x-nullable) - [x-nullable](#x-nullable)
- [How to use with Redoc](#how-to-use-with-redoc-7) - [How to use with Redoc](#how-to-use-with-redoc-7)
- [x-extendedDiscriminator](#x-extendeddiscriminator) - [x-extendedDiscriminator](#x-extendeddiscriminator)
- [How to use with Redoc](#how-to-use-with-redoc-8) - [How to use with Redoc](#how-to-use-with-redoc-8)
- [x-extendedDiscriminator example](#x-extendeddiscriminator-example) - [x-extendedDiscriminator example](#x-extendeddiscriminator-example)
- [x-additionalPropertiesName](#x-additionalpropertiesname) - [x-additionalPropertiesName](#x-additionalpropertiesname)
- [How to use with Redoc](#how-to-use-with-redoc-9) - [How to use with Redoc](#how-to-use-with-redoc-9)
- [x-additionalPropertiesName example](#x-additionalpropertiesname-example) - [x-additionalPropertiesName example](#x-additionalpropertiesname-example)
- [x-explicitMappingOnly](#x-explicitmappingonly) - [x-explicitMappingOnly](#x-explicitmappingonly)
- [How to use with Redoc](#how-to-use-with-redoc-10) - [How to use with Redoc](#how-to-use-with-redoc-10)
- [x-explicitMappingOnly example](#x-explicitmappingonly-example) - [x-explicitMappingOnly example](#x-explicitmappingonly-example)
### Swagger Object ## Swagger Object
Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi/) 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. 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 | | 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. `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! 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!
<a name="tagGroupObject"></a> <a name="tagGroupObject"></a>
#### Tag Group Object #### Tag Group Object
Information about tags group Information about tags group
###### Fixed fields ##### Fixed fields
| Field Name | Type | Description | | Field Name | Type | Description |
| :---------- | :--------: | :---------- | | :---------- | :--------: | :---------- |
| name | string | The group name | | name | string | The group name |
| tags | [ string ] | List of tags to include in this group | tags | [ string ] | List of tags to include in this group
###### x-tagGroups example #### x-tagGroups example
json json
```json ```json
{ {
@ -104,18 +105,18 @@ x-tagGroups:
- Secondary Stats - Secondary Stats
``` ```
#### x-ignoredHeaderParameters ### x-ignoredHeaderParameters
| Field Name | Type | Description | | Field Name | Type | Description |
| :-------------------------- | :-----------: | :---------- | | :-------------------------- | :-----------: | :---------- |
| x-ignoredHeaderParameters | [ string ] | A list of ignored headers | | 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. Use `x-ignoredHeaderParameters` to specify header parameter names which are ignored by Redoc.
###### x-ignoredHeaderParameters example #### x-ignoredHeaderParameters example
```yaml ```yaml
swagger: '2.0' swagger: '2.0'
info: info:
@ -127,23 +128,25 @@ x-ignoredHeaderParameters:
- X-Test-Header - X-Test-Header
``` ```
### Info Object ## Info Object
Extends the OpenAPI [Info Object](https://redocly.com/docs/openapi-visual-reference/info/) 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 | | 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. `x-logo` is used to specify API logo. The corresponding image is displayed just above the side-menu.
<a name="logoObject"></a> <a name="logoObject"></a>
#### Logo Object #### Logo Object
The information about API logo The information about API logo
###### Fixed fields #### Fixed fields
| Field Name | Type | Description | | 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 | 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) | 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. | 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
```json ```json
{ {
@ -177,19 +180,19 @@ info:
altText: "Petstore logo" altText: "Petstore logo"
``` ```
### Tag Object ## Tag Object
Extends the OpenAPI [Tag Object](https://redocly.com/docs/openapi-visual-reference/tags/) Extends the OpenAPI [Tag Object](https://redocly.com/docs/openapi-visual-reference/tags/)
#### x-traitTag ### x-traitTag
| Field Name | Type | Description | | 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) | | 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. 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. This is useful for handling out common things like Pagination, Rate-Limits, etc.
###### x-traitTag example #### x-traitTag example
json json
```json ```json
{ {
@ -205,36 +208,37 @@ description: Pagination description (can use markdown syntax)
x-traitTag: true 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 | | 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/) Extends the OpenAPI [Operation Object](https://redocly.com/docs/openapi-visual-reference/operation/)
#### x-codeSamples ### x-codeSamples
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-codeSamples | [ [Code Sample Object](#code-sample-object) ] | A list of code samples associated with operation | | 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. `x-codeSamples` are rendered on the right panel in Redoc.
<a name="codeSampleObject"></a> <a name="codeSampleObject"></a>
#### Code Sample Object
### Code Sample Object
Operation code sample Operation code sample
###### Fixed fields #### Fixed fields
| Field Name | Type | Description | | 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) | | 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 | | label | string? | Code sample label, for example `Node` or `Python2.7`, _optional_, `lang` is used by default |
| source | string | Code sample source code | | source | string | Code sample source code |
###### Code Sample Object example #### Code Sample Object example
json json
```json ```json
{ {
@ -248,53 +252,53 @@ lang: JavaScript
source: console.log('Hello World'); source: console.log('Hello World');
``` ```
### Parameter Object ## Parameter Object
Extends the OpenAPI [Parameter Object](https://redocly.com/docs/openapi-visual-reference/parameter/) Extends the OpenAPI [Parameter Object](https://redocly.com/docs/openapi-visual-reference/parameter/)
#### x-examples ### x-examples
| Field Name | Type | Description | | 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` | | 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. `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/). Extends the OpenAPI [Response Object](https://redocly.com/docs/openapi-visual-reference/response/).
#### x-summary ### x-summary
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| 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
Extends the OpenAPI [Schema Object](https://redocly.com/docs/openapi-visual-reference/schemas/) Extends the OpenAPI [Schema Object](https://redocly.com/docs/openapi-visual-reference/schemas/)
#### x-nullable ### x-nullable
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| 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 is used as an extended 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 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
```yaml ```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`. 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.
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| 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
```yaml ```yaml
Player: Player:
@ -362,20 +366,20 @@ Player:
type: string type: string
``` ```
#### 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.
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| 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 lists only the explicitly defined mappings. When `false`, the default behavior is kept, in other words, explicit and implicit mappings are shown. 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 ```yaml

4
docs/security-definitions-injection.md
View File

@ -4,7 +4,7 @@ You can inject the Security Definitions widget anywhere in your specification `d
```markdown ```markdown
... ...
# Authorization ## Authorization
Some description Some description
@ -14,7 +14,7 @@ Some description
The inject instruction is wrapped in an HTML comment, The inject instruction is wrapped in an HTML comment,
so it is **visible only in Redoc** and not visible, for instance, in the SwaggerUI. 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 If the injection tag is not found in the description, it is appended to the end
of description under the `Authentication` header. of description under the `Authentication` header.