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

docs: update options for future major release

Browse Source
This commit is contained in:
Alex Varchuk 2025-01-14 16:29:29 +01:00
parent 59ee73fefa
commit 38e109e7f4
No known key found for this signature in database
GPG Key ID: 8A9260AE529FF454
4 changed files with 2 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -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

90
docs/config.md
View File

@ -26,54 +26,18 @@ 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
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.
@ -88,28 +52,10 @@ _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
Shows required properties in schemas first, ordered in the same order as in the required array.
@ -132,37 +78,7 @@ 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.
### showObjectSchemaExamples
Shows object schema example in the properties; default `false`.
### showWebhookVerb
When set to `true`, shows the HTTP request method for webhooks in operations and in the sidebar.
### simpleOneOfTypeLabel
Shows only unique `oneOf` types in the label without titles.
### sortEnumValuesAlphabetically
When set to `true`, sorts all enum values in all schemas alphabetically.
### sortOperationsAlphabetically
When set to `true`, sorts operations in the navigation sidebar and in the middle panel alphabetically.
### sortPropsAlphabetically
When set to `true`, sorts properties in all schemas alphabetically.
### sortTagsAlphabetically
When set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically. Note that only tags are sorted alphabetically in the middle panel, not the operations associated with each tag. To sort operations alphabetically as well, you must set the `sortOperationsAlphabetically` setting to `true`.
_Default: false_
### untrustedDefinition
### sanitize
If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.
@ -248,7 +164,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 +173,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

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

@ -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,9 +36,6 @@ 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)
@ -105,29 +99,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 +261,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.

1
src/utils/openapi.ts
View File

@ -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,