diff --git a/README.md b/README.md index 94d1452d..cb79ec89 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 28e24f7e..2e350253 100644 --- a/docs/config.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index a98776c2..6e2716e8 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 792eeefb..9ed239ce 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 1d3a33c5..df2f91ed 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,