mirror of
https://github.com/Redocly/redoc.git
synced 2025-03-09 20:35:48 +03:00
docs: update options for future major release (#2646)
This commit is contained in:
Alex Varchuk
GitHub
parent
153ec7a0b7
commit
ae1ae79901
|
|
@ -122,10 +122,8 @@ Redoc uses the following [specification extensions](https://redocly.com/docs/api
|
|||
* [`x-displayName`](docs/redoc-vendor-extensions.md#x-displayname) - specify human-friendly names for the menu categories
|
||||
* [`x-tagGroups`](docs/redoc-vendor-extensions.md#x-tagGroups) - group tags by categories in the side menu
|
||||
* [`x-servers`](docs/redoc-vendor-extensions.md#x-servers) - ability to specify different servers for API (backported from OpenAPI 3.0)
|
||||
* [`x-ignoredHeaderParameters`](docs/redoc-vendor-extensions.md#x-ignoredHeaderParameters) - ability to specify header parameter names to ignore
|
||||
* [`x-additionalPropertiesName`](docs/redoc-vendor-extensions.md#x-additionalPropertiesName) - ability to supply a descriptive name for the additional property keys
|
||||
* [`x-summary`](docs/redoc-vendor-extensions.md#x-summary) - for Response object, use as the response button text, with description rendered under the button
|
||||
* [`x-extendedDiscriminator`](docs/redoc-vendor-extensions.md#x-extendedDiscriminator) - in Schemas, uses this to solve name-clash issues with the standard discriminator
|
||||
* [`x-explicitMappingOnly`](docs/redoc-vendor-extensions.md#x-explicitMappingOnly) - in Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object
|
||||
|
||||
## Releases
|
||||
|
|
|
|||
181
docs/config.md
181
docs/config.md
|
|
@ -26,59 +26,19 @@ Sets the minimum amount of characters that need to be typed into the search dial
|
|||
|
||||
_Default: 3_
|
||||
|
||||
### expandDefaultServerVariables
|
||||
|
||||
Enables or disables expanding default server variables.
|
||||
|
||||
### expandResponses
|
||||
|
||||
Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, for example `expandResponses='200,201'`. Special value 'all' expands all responses by default. Be careful: this option can slow down documentation rendering time.
|
||||
|
||||
### expandSingleSchemaField
|
||||
|
||||
Automatically expands the single field in a schema.
|
||||
|
||||
### hideDownloadButton
|
||||
### hideDownloadButtons
|
||||
|
||||
Hides the 'Download' button for saving the API definition source file. **This setting does not make the API definition private**; it just hides the button.
|
||||
|
||||
### hideHostname
|
||||
|
||||
If set to `true`, the protocol and hostname are not shown in the operation definition.
|
||||
|
||||
### hideLoading
|
||||
|
||||
Hides the loading animation. Does not apply to CLI or Workflows-rendered docs.
|
||||
|
||||
### hideRequestPayloadSample
|
||||
|
||||
Hides request payload examples.
|
||||
|
||||
### hideOneOfDescription
|
||||
|
||||
If set to `true`, the description for `oneOf`/`anyOf` object is not shown in the schema.
|
||||
|
||||
### hideSchemaPattern
|
||||
|
||||
If set to `true`, the pattern is not shown in the schema.
|
||||
|
||||
### hideSchemaTitles
|
||||
|
||||
Hides the schema title next to to the type.
|
||||
|
||||
### hideSecuritySection
|
||||
|
||||
Hides the Security panel section.
|
||||
|
||||
### hideSingleRequestSampleTab
|
||||
|
||||
Hides the request sample tab for requests with only one sample.
|
||||
|
||||
### htmlTemplate
|
||||
|
||||
Sets the path to the optional HTML file used to modify the layout of the reference docs page.
|
||||
|
||||
### jsonSampleExpandLevel
|
||||
### jsonSamplesExpandLevel
|
||||
|
||||
Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value `all` that expands all levels.
|
||||
|
||||
|
|
@ -88,35 +48,17 @@ _Default: 2_
|
|||
|
||||
Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed.
|
||||
|
||||
### menuToggle
|
||||
|
||||
If set to `true`, selecting an expanded item in the sidebar twice collapses it.
|
||||
|
||||
_Default: true_
|
||||
|
||||
### nativeScrollbars
|
||||
|
||||
If set to `true`, the sidebar uses the native scrollbar instead of perfect-scroll. This setting is a scrolling performance optimization for big API definitions.
|
||||
|
||||
### onlyRequiredInSamples
|
||||
|
||||
Shows only required fields in request samples.
|
||||
|
||||
### pathInMiddlePanel
|
||||
|
||||
Shows the path link and HTTP verb in the middle panel instead of the right panel.
|
||||
|
||||
### payloadSampleIdx
|
||||
|
||||
If set, the payload sample is inserted at the specified index. If there are `N` payload samples and the value configured here is bigger than `N`, the payload sample is inserted last. Indexes start from 0.
|
||||
|
||||
### requiredPropsFirst
|
||||
### sortRequiredPropsFirst
|
||||
|
||||
Shows required properties in schemas first, ordered in the same order as in the required array.
|
||||
|
||||
### schemaExpansionLevel
|
||||
### schemasExpansionLevel
|
||||
|
||||
Specifies whether to automatically expand schemas in Reference docs. Set it to `all` to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, `schemaExpansionLevel: 3` expands schemas up to three levels deep. The default value is `0`, meaning no schemas are expanded automatically.
|
||||
Specifies whether to automatically expand schemas in Reference docs. Set it to `all` to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, `schemasExpansionLevel: 3` expands schemas up to three levels deep. The default value is `0`, meaning no schemas are expanded automatically.
|
||||
|
||||
### scrollYOffset
|
||||
|
||||
|
|
@ -132,6 +74,111 @@ Note that you can specify the `scrollYOffset` value in any of the following ways
|
|||
|
||||
Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be boolean or an array of strings with names of extensions to display. When used as boolean and set to `true`, all specification extensions are shown.
|
||||
|
||||
### sanitize
|
||||
|
||||
If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.
|
||||
|
||||
### downloadUrls
|
||||
|
||||
Set the URLs used to download the OpenAPI description or other documentation related files from the API documentation page.
|
||||
|
||||
### schemaDefinitionsTagName
|
||||
|
||||
If a value is set, all of the schemas are rendered with the designated tag name. The schemas then render and display in the sidebar navigation (with that associated tag name).
|
||||
|
||||
### generatedSamplesMaxDepth
|
||||
|
||||
The generatedSamplesMaxDepth option controls how many schema levels automatically generated for payload samples. The default is 8 which works well for most APIs, but you can adjust it if necessary for your use case.
|
||||
|
||||
### hidePropertiesPrefix
|
||||
|
||||
In complex data structures or object schemas where properties are nested within parent objects the hidePropertiesPrefix option enables the hiding of parent names for nested properties within the documentation.
|
||||
|
||||
_Default: true_
|
||||
|
||||
## Deprecated Functional settings
|
||||
|
||||
### hideDownloadButton
|
||||
|
||||
Hides the 'Download' button for saving the API definition source file. **This setting does not make the API definition private**; it just hides the button.
|
||||
|
||||
### downloadFileName
|
||||
|
||||
Sets the filename for the downloaded API definition source file.
|
||||
|
||||
### downloadDefinitionUrl
|
||||
|
||||
Sets the URL for the downloaded API definition source file.
|
||||
|
||||
### requiredPropsFirst
|
||||
|
||||
Shows required properties in schemas first, ordered in the same order as in the required array.
|
||||
|
||||
### jsonSampleExpandLevel
|
||||
|
||||
Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value `all` that expands all levels.
|
||||
|
||||
_Default: 2_
|
||||
|
||||
### schemaExpansionLevel
|
||||
|
||||
Specifies whether to automatically expand schemas in Reference docs. Set it to `all` to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, `schemaExpansionLevel: 3` expands schemas up to three levels deep. The default value is `0`, meaning no schemas are expanded automatically.
|
||||
|
||||
|
||||
### expandDefaultServerVariables
|
||||
|
||||
Enables or disables expanding default server variables.
|
||||
|
||||
### expandResponses
|
||||
|
||||
Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, for example `expandResponses='200,201'`. Special value 'all' expands all responses by default. Be careful: this option can slow down documentation rendering time.
|
||||
|
||||
### expandSingleSchemaField
|
||||
|
||||
Automatically expands the single field in a schema.
|
||||
|
||||
### hideHostname
|
||||
|
||||
If set to `true`, the protocol and hostname are not shown in the operation definition.
|
||||
|
||||
### hideRequestPayloadSample
|
||||
|
||||
Hides request payload examples.
|
||||
|
||||
### hideOneOfDescription
|
||||
|
||||
If set to `true`, the description for `oneOf`/`anyOf` object is not shown in the schema.
|
||||
|
||||
### hideSchemaPattern
|
||||
|
||||
If set to `true`, the pattern is not shown in the schema.
|
||||
|
||||
### hideSecuritySection
|
||||
|
||||
Hides the Security panel section.
|
||||
|
||||
### hideSingleRequestSampleTab
|
||||
|
||||
Hides the request sample tab for requests with only one sample.
|
||||
|
||||
### menuToggle
|
||||
|
||||
If set to `true`, selecting an expanded item in the sidebar twice collapses it.
|
||||
|
||||
_Default: true_
|
||||
|
||||
### nativeScrollbars
|
||||
|
||||
If set to `true`, the sidebar uses the native scrollbar instead of perfect-scroll. This setting is a scrolling performance optimization for big API definitions.
|
||||
|
||||
### pathInMiddlePanel
|
||||
|
||||
Shows the path link and HTTP verb in the middle panel instead of the right panel.
|
||||
|
||||
### payloadSampleIdx
|
||||
|
||||
If set, the payload sample is inserted at the specified index. If there are `N` payload samples and the value configured here is bigger than `N`, the payload sample is inserted last. Indexes start from 0.
|
||||
|
||||
### showObjectSchemaExamples
|
||||
|
||||
Shows object schema example in the properties; default `false`.
|
||||
|
|
@ -162,12 +209,12 @@ When set to true, sorts tags in the navigation sidebar and in the middle panel a
|
|||
|
||||
_Default: false_
|
||||
|
||||
### untrustedDefinition
|
||||
### untrustedSpec
|
||||
|
||||
If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.
|
||||
|
||||
## Theme settings
|
||||
|
||||
Change styles for the API documentation page. **Supported in Redoc CE 2.x**.
|
||||
* `spacing`
|
||||
* `unit`: 5 # main spacing unit used in autocomputed theme values later
|
||||
* `sectionHorizontal`: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
|
||||
|
|
@ -248,7 +295,7 @@ For more information, refer to [Security definitions injection](./security-defin
|
|||
|
||||
### OpenAPI specification extensions
|
||||
|
||||
Redoc uses the following [specification extensions](https://redocly.com/docs/api-reference-docs/spec-extensions/):
|
||||
Redoc uses the following [specification extensions](https://redocly.com/docs-legacy/api-reference-docs/spec-extensions/):
|
||||
* [`x-logo`](./redoc-vendor-extensions.md#x-logo) - is used to specify API logo
|
||||
* [`x-traitTag`](./redoc-vendor-extensions.md#x-traittag) - useful for handling out common things like Pagination, Rate-Limits, etc
|
||||
* [`x-codeSamples`](./redoc-vendor-extensions.md#x-codesamples) - specify operation code samples
|
||||
|
|
@ -257,10 +304,8 @@ Redoc uses the following [specification extensions](https://redocly.com/docs/api
|
|||
* [`x-displayName`](./redoc-vendor-extensions.md#x-displayname) - specify human-friendly names for the menu categories
|
||||
* [`x-tagGroups`](./redoc-vendor-extensions.md#x-taggroups) - group tags by categories in the side menu
|
||||
* [`x-servers`](./redoc-vendor-extensions.md#x-servers) - ability to specify different servers for API (backported from OpenAPI 3.0)
|
||||
* [`x-ignoredHeaderParameters`](./redoc-vendor-extensions.md#x-ignoredheaderparameters) - ability to specify header parameter names to ignore
|
||||
* [`x-additionalPropertiesName`](./redoc-vendor-extensions.md#x-additionalpropertiesname) - ability to supply a descriptive name for the additional property keys
|
||||
* [`x-summary`](./redoc-vendor-extensions.md#x-summary) - For Response object, use as the response button text, with description rendered under the button
|
||||
* [`x-extendedDiscriminator`](./redoc-vendor-extensions.md#x-extendeddiscriminator) - In Schemas, uses this to solve name-clash issues with the standard discriminator
|
||||
* [`x-explicitMappingOnly`](./redoc-vendor-extensions.md#x-explicitmappingonly) - In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -67,7 +67,7 @@ theme:
|
|||
openapi:
|
||||
disableSearch: true
|
||||
expandResponses: 200,202
|
||||
jsonSampleExpandLevel: 1
|
||||
jsonSamplesExpandLevel: 1
|
||||
|
||||
theme:
|
||||
sidebar:
|
||||
|
|
|
|||
|
|
@ -10,9 +10,6 @@ You can use the following [vendor extensions](https://redocly.com/docs/openapi-v
|
|||
- [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)
|
||||
|
|
@ -39,21 +36,21 @@ You can use the following [vendor extensions](https://redocly.com/docs/openapi-v
|
|||
- [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)
|
||||
- [x-enumDescriptions](#x-enumdescriptions)
|
||||
- [How to use with Redoc](#how-to-use-with-redoc-11)
|
||||
- [x-enumDescriptions example](#x-enumdescriptions-example)
|
||||
|
||||
## Swagger Object
|
||||
Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi)
|
||||
|
||||
### 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/main/versions/3.0.0.md#server-object). Currently doesn't support templates.
|
||||
|
||||
### x-tagGroups
|
||||
|
||||
|
|
@ -105,29 +102,6 @@ x-tagGroups:
|
|||
- Secondary Stats
|
||||
```
|
||||
|
||||
### x-ignoredHeaderParameters
|
||||
|
||||
|
||||
| Field Name | Type | Description |
|
||||
| :-------------------------- | :-----------: | :---------- |
|
||||
| x-ignoredHeaderParameters | [ string ] | A list of ignored headers |
|
||||
|
||||
|
||||
#### How to use with Redoc
|
||||
Use `x-ignoredHeaderParameters` to specify header parameter names which are ignored by Redoc.
|
||||
|
||||
#### x-ignoredHeaderParameters example
|
||||
```yaml
|
||||
swagger: '2.0'
|
||||
info:
|
||||
...
|
||||
tags: [...]
|
||||
x-ignoredHeaderParameters:
|
||||
- Accept
|
||||
- User-Agent
|
||||
- X-Test-Header
|
||||
```
|
||||
|
||||
## Info Object
|
||||
Extends the OpenAPI [Info Object](https://redocly.com/docs/openapi-visual-reference/info/)
|
||||
|
||||
|
|
@ -290,59 +264,6 @@ Extends the OpenAPI [Schema Object](https://redocly.com/docs/openapi-visual-refe
|
|||
#### 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.
|
||||
|
||||
| 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`.
|
||||
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
|
||||
|
||||
```yaml
|
||||
|
||||
Payment:
|
||||
x-extendedDiscriminator: type
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
|
||||
CashPayment:
|
||||
allOf:
|
||||
- $ref: "#/definitions/Payment"
|
||||
- properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- cash
|
||||
currency:
|
||||
type: string
|
||||
|
||||
PayPalPayment:
|
||||
allOf:
|
||||
- $ref: "#/definitions/Payment"
|
||||
- properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- paypal
|
||||
userEmail:
|
||||
type: string
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -402,3 +323,31 @@ Pet:
|
|||
```
|
||||
|
||||
Shows in the selectpicker only the items `cat` and `bee`, even though the `Dog` class inherits from the `Pet` class.
|
||||
|
||||
### x-enumDescriptions
|
||||
| Field Name | Type | Description |
|
||||
| :------------- | :------: | :---------- |
|
||||
| x-enumDescriptions | [[Enum Description Object](https://redocly.com/docs/realm/author/reference/openapi-extensions/x-enum-descriptions#enum-description-object)] | A list of the enum values and descriptions to include in the documentation. |
|
||||
|
||||
#### How to use with Redoc
|
||||
The enum (short for "enumeration") fields in OpenAPI allow you to restrict the value of a field to a list of allowed values. These values need to be short and machine-readable, but that can make them harder for humans to parse and work with.
|
||||
|
||||
Add x-enumDescriptions to your OpenAPI description to show a helpful table of enum options and an explanation of what each one means. This field supports Markdown.
|
||||
|
||||
#### x-enumDescriptions example
|
||||
The following example shows a schema with two short-named options, and the x-enumDescriptions entry to list all enum entries and give additional context for each:
|
||||
|
||||
```yaml
|
||||
components:
|
||||
schemas:
|
||||
TicketType:
|
||||
description: Type of ticket being purchased. Use `general` for regular museum entry and `event` for tickets to special events.
|
||||
type: string
|
||||
enum:
|
||||
- event
|
||||
- general
|
||||
x-enumDescriptions:
|
||||
event: Event Tickets _(timed entry)_
|
||||
general: General Admission
|
||||
example: event
|
||||
```
|
||||
|
|
|
|||
|
|
@ -654,7 +654,6 @@ export function isRedocExtension(key: string): boolean {
|
|||
'x-codeSamples': true,
|
||||
'x-displayName': true,
|
||||
'x-examples': true,
|
||||
'x-ignoredHeaderParameters': true,
|
||||
'x-logo': true,
|
||||
'x-nullable': true,
|
||||
'x-servers': true,
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user