diff --git a/README.md b/README.md index 94d1452d1..cb79ec89d 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/config.md b/docs/config.md index 28e24f7ed..2e350253d 100644 --- a/docs/config.md +++ b/docs/config.md @@ -26,111 +26,158 @@ 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. +### hideDownloadButtons -### expandResponses +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. -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. +### hideLoading -### expandSingleSchemaField +Hides the loading animation. Does not apply to CLI or Workflows-rendered docs. -Automatically expands the single field in a schema. +### hideSchemaTitles -### hideDownloadButton +Hides the schema title next to to the type. -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. +### jsonSamplesExpandLevel -### hideHostname +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. -If set to `true`, the protocol and hostname are not shown in the operation definition. +_Default: 2_ -### hideLoading +### maxDisplayedEnumValues -Hides the loading animation. Does not apply to CLI or Workflows-rendered docs. +Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed. -### hideRequestPayloadSample +### onlyRequiredInSamples -Hides request payload examples. +Shows only required fields in request samples. -### hideOneOfDescription +### sortRequiredPropsFirst -If set to `true`, the description for `oneOf`/`anyOf` object is not shown in the schema. +Shows required properties in schemas first, ordered in the same order as in the required array. -### hideSchemaPattern +### schemasExpansionLevel -If set to `true`, the pattern is not shown in the schema. +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. -### hideSchemaTitles +### scrollYOffset -Hides the schema title next to to the type. +Specifies a vertical scroll-offset. +This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc. -### hideSecuritySection +Note that you can specify the `scrollYOffset` value in any of the following ways: +- as a number - a fixed number of pixels to be used as the offset. +- as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as the offset. +- a function (advanced) - a getter function. Must return a number representing the offset (in pixels). -Hides the Security panel section. +### showExtensions -### hideSingleRequestSampleTab +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. -Hides the request sample tab for requests with only one sample. +### sanitize -### htmlTemplate +If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS. -Sets the path to the optional HTML file used to modify the layout of the reference docs page. +### downloadUrls -### jsonSampleExpandLevel +Set the URLs used to download the OpenAPI description or other documentation related files from the API documentation page. -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. +### schemaDefinitionsTagName -_Default: 2_ +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). -### maxDisplayedEnumValues +### generatedSamplesMaxDepth -Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed. +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. -### menuToggle +### hidePropertiesPrefix -If set to `true`, selecting an expanded item in the sidebar twice collapses it. +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_ -### 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. +## Deprecated Functional settings -### onlyRequiredInSamples +### hideDownloadButton -Shows only required fields in request samples. +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. -### pathInMiddlePanel +### downloadFileName -Shows the path link and HTTP verb in the middle panel instead of the right panel. +Sets the filename for the downloaded API definition source file. -### payloadSampleIdx +### downloadDefinitionUrl -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. +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. -### scrollYOffset -Specifies a vertical scroll-offset. -This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc. +### expandDefaultServerVariables -Note that you can specify the `scrollYOffset` value in any of the following ways: -- as a number - a fixed number of pixels to be used as the offset. -- as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as the offset. -- a function (advanced) - a getter function. Must return a number representing the offset (in pixels). +Enables or disables expanding default server variables. -### showExtensions +### expandResponses -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. +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 @@ -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 diff --git a/docs/index.md b/docs/index.md index a98776c21..6e2716e8e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -67,7 +67,7 @@ theme: openapi: disableSearch: true expandResponses: 200,202 - jsonSampleExpandLevel: 1 + jsonSamplesExpandLevel: 1 theme: sidebar: diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 792eeefb8..9ed239cef 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.md @@ -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 +``` diff --git a/src/utils/openapi.ts b/src/utils/openapi.ts index 1d3a33c5f..df2f91edc 100644 --- a/src/utils/openapi.ts +++ b/src/utils/openapi.ts @@ -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,