Redocly/redoc
1
1
Fork 0
mirror of https://github.com/Redocly/redoc.git synced 2025-02-16 18:00:33 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: improvements to vendor extensions topic (#1386)

Browse Source
This commit is contained in:
Swapnil Ogale 2020-10-13 22:55:45 +11:00 committed by GitHub
parent 6632d84453
commit 0c782ec51f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 69 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,8 +1,34 @@
# ReDoc vendor extensions # ReDoc vendor extensions
ReDoc makes use of the following [vendor extensions](https://swagger.io/specification/#specificationExtensions)
### Swagger Object vendor extensions You can use the following [vendor extensions](https://swagger.io/specification/#specificationExtensions) with Redoc.
Extend OpenAPI root [Swagger Object](https://swagger.io/specification/#oasObject)
- [Swagger Object](#swagger-object)
- [x-servers](#x-servers)
- [x-tagGroups](#x-taggroups)
- [Tag Group Object](#a-nametaggroupobjectatag-group-object)
- [x-ignoredHeaderParameters](#x-ignoredheaderparameters)
- [Info Object](#info-object)
- [x-logo](#x-logo)
- [Logo Object](#a-namelogoobjectalogo-object)
- [Tag Object](#tag-object)
- [x-traitTag](#x-traittag)
- [x-displayName](#x-displayname)
- [Operation Object](#operation-object-vendor-extensions)
- [x-codeSamples](#x-codesamples)
- [Code Sample Object](#a-namecodesampleobjectacode-sample-object)
- [Parameter Object](#parameter-object)
- [x-examples](#x-examples)
- [Response Object vendor extensions](#response-object-vendor-extensions)
- [x-summary](#x-summary)
- [Schema Object](#schema-object)
- [x-nullable](#x-nullable)
- [x-extendedDiscriminator](#x-extendeddiscriminator)
- [x-additionalPropertiesName](#x-additionalpropertiesname)
- [x-explicitMappingOnly](#x-explicitmappingonly)
### Swagger Object
Extends the OpenAPI root [OpenAPI Object](https://swagger.io/specification/#oasObject)
#### 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.
@ -12,9 +38,9 @@ Backported from OpenAPI 3.0 [`servers`](https://github.com/OAI/OpenAPI-Specifica
| :------------- | :-----------: | :---------- | | :------------- | :-----------: | :---------- |
| x-tagGroups | [ [Tag Group Object](#tagGroupObject) ] | A list of tag groups | | x-tagGroups | [ [Tag Group Object](#tagGroupObject) ] | A list of tag groups |
###### Usage in 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.
If you are going to use `x-tagGroups`, please make sure you **add all tags to a group**, since a tag that is not in a group, **will not be 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, **will not be displayed** at all!
#### <a name="tagGroupObject"></a>Tag Group Object #### <a name="tagGroupObject"></a>Tag Group Object
Information about tags group Information about tags group
@ -62,8 +88,8 @@ x-tagGroups:
| x-ignoredHeaderParameters | [ string ] | A list of ignored headers | | x-ignoredHeaderParameters | [ string ] | A list of ignored headers |
###### Usage in Redoc ###### How to use with Redoc
`x-ignoredHeaderParameters` is used 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
@ -77,19 +103,20 @@ x-ignoredHeaderParameters:
- X-Test-Header - X-Test-Header
``` ```
### Info Object vendor extensions ### Info Object
Extends OpenAPI [Info Object](http://swagger.io/specification/#infoObject) Extends the OpenAPI [Info Object](http://swagger.io/specification/#infoObject)
#### x-logo #### x-logo
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :-----------: | :---------- | | :------------- | :-----------: | :---------- |
| x-logo | [Logo Object](#logoObject) | The information about API logo | | x-logo | [Logo Object](#logoObject) | The information about API logo |
###### Usage in Redoc ###### How to use with Redoc
`x-logo` is used to specify API logo. The corresponding image are displayed just above side-menu. `x-logo` is used to specify API logo. The corresponding image is displayed just above the side-menu.
#### <a name="logoObject"></a>Logo Object #### <a name="logoObject"></a>Logo Object
The information about API logo The information about API logo
###### Fixed fields ###### Fixed fields
| Field Name | Type | Description | | Field Name | Type | Description |
| :-------------- | :------: | :---------- | | :-------------- | :------: | :---------- |
@ -125,17 +152,16 @@ info:
altText: "Petstore logo" altText: "Petstore logo"
``` ```
### Tag Object
Extends the OpenAPI [Tag Object](http://swagger.io/specification/#tagObject)
### Tag Object vendor extensions
Extends OpenAPI [Tag Object](http://swagger.io/specification/#tagObject)
#### 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) |
###### Usage in Redoc ###### How to use with Redoc
Tags that have `x-traitTag` set to `true` are listed in side-menu but don't have any subitems (operations). Tag `description` is rendered as well. 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
@ -161,17 +187,19 @@ x-traitTag: true
| 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 OpenAPI [Operation Object](http://swagger.io/specification/#operationObject) Extends the OpenAPI [Operation Object](http://swagger.io/specification/#operationObject)
#### x-codeSamples #### x-codeSamples
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-codeSamples | [ [Code Sample Object](#codeSampleObject) ] | A list of code samples associated with operation | | x-codeSamples | [ [Code Sample Object](#codeSampleObject) ] | A list of code samples associated with operation |
###### Usage in ReDoc ###### How to use with ReDoc
`x-codeSamples` are rendered on the right panel of ReDoc `x-codeSamples` are rendered on the right panel in ReDoc.
#### <a name="codeSampleObject"></a>Code Sample Object #### <a name="codeSampleObject"></a>Code Sample Object
Operation code sample Operation code sample
###### Fixed fields ###### Fixed fields
| Field Name | Type | Description | | Field Name | Type | Description |
| :---------- | :------: | :----------- | | :---------- | :------: | :----------- |
@ -194,49 +222,51 @@ lang: JavaScript
source: console.log('Hello World'); source: console.log('Hello World');
``` ```
### Parameter Object vendor extensions ### Parameter Object
Extends OpenAPI [Parameter Object](http://swagger.io/specification/#parameterObject) Extends the OpenAPI [Parameter Object](http://swagger.io/specification/#parameterObject)
#### x-examples #### x-examples
| Field Name | Type | Description | | Field Name | Type | Description |
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| 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` | | 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` |
###### Usage in ReDoc ###### How to use with ReDoc
`x-examples` are rendered in the JSON tab on the right panel of ReDoc. `x-examples` are rendered in the JSON tab on the right panel in ReDoc.
### Response Object vendor extensions ### Response Object vendor extensions
Extends OpenAPI [Response Object](https://swagger.io/specification/#responseObject) Extends the OpenAPI [Response Object](https://swagger.io/specification/#responseObject)
#### 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 |
###### Usage in ReDoc ###### How to use with ReDoc
If specified, `x-summary` is used as the response button text. Description is rendered under the button. If specified, you can use `x-summary` as the response button text, with description rendered under the button.
### Schema Object
Extends the OpenAPI [Schema Object](http://swagger.io/specification/#schemaObject)
### Schema Object vendor extensions
Extends OpenAPI [Schema Object](http://swagger.io/specification/#schemaObject)
#### 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 |
###### Usage in 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 ReDoc-specific vendor extension. It won't be 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 |
###### Usage in 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 will be used as a extended 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 definition with selectpicker using which user can select value of the `x-extendedDiscriminator`-marked field.
ReDoc displays the definition which is 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
@ -276,11 +306,10 @@ PayPalPayment:
type: string type: string
``` ```
In the example above the names of definitions (`PayPalPayment`) are named differently than 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`.
names in the payload (`paypal`) which is not supported by default `discriminator`.
#### x-additionalPropertiesName #### x-additionalPropertiesName
**ATTENTION**: This is ReDoc-specific vendor extension. It won't be 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.
@ -288,7 +317,7 @@ Extends the `additionalProperties` property of the schema object.
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-additionalPropertiesName | string | descriptive name of additional properties keys | | x-additionalPropertiesName | string | descriptive name of additional properties keys |
###### Usage in 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
@ -308,7 +337,7 @@ Player:
``` ```
#### x-explicitMappingOnly #### x-explicitMappingOnly
**ATTENTION**: This is ReDoc-specific vendor extension. It won't be 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.
@ -316,10 +345,9 @@ Extends the `discriminator` property of the schema object.
| :------------- | :------: | :---------- | | :------------- | :------: | :---------- |
| x-explicitMappingOnly | boolean | limit the discriminator selectpicker to the explicit mappings only | | x-explicitMappingOnly | boolean | limit the discriminator selectpicker to the explicit mappings only |
###### Usage in 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 will only list the the explicitly defined mappings. When `false`, 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.
the default behavior is kept, i.e. explicit and implicit mappings will be shown.
###### x-explicitMappingOnly example ###### x-explicitMappingOnly example
@ -338,5 +366,4 @@ Pet:
bee: "#/components/schemas/HoneyBee" bee: "#/components/schemas/HoneyBee"
``` ```
Will show in the selectpicker only the items `cat` and `bee`, even though the `Dog` class inherits from Will show in the selectpicker only the items `cat` and `bee`, even though the `Dog` class inherits from the `Pet` class.
the `Pet` class.