mirror of
https://github.com/Redocly/redoc.git
synced 2024-11-10 19:06:34 +03:00
sync: Synced local 'docs/' with remote 'docs/redoc/'
This commit is contained in:
redocly-bot
parent
b2d8e0f5b7
commit
7b2931dc91
|
|
@ -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`.
|
||||
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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!
|
||||
|
||||
<a name="tagGroupObject"></a>
|
||||
|
||||
#### 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.
|
||||
|
||||
<a name="logoObject"></a>
|
||||
|
||||
#### 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.
|
||||
|
||||
<a name="codeSampleObject"></a>
|
||||
#### 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user