From 38e109e7f4c949caaeb21a4c30c8e2698f9cf41a Mon Sep 17 00:00:00 2001 From: Alex Varchuk Date: Tue, 14 Jan 2025 16:29:29 +0100 Subject: [PATCH 1/8] docs: update options for future major release --- README.md | 2 - docs/config.md | 90 +-------------------------------- docs/redoc-vendor-extensions.md | 82 ------------------------------ src/utils/openapi.ts | 1 - 4 files changed, 2 insertions(+), 173 deletions(-) diff --git a/README.md b/README.md index 94d1452d16..cb79ec89da 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 28e24f7eda..6f1f477e56 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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 diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 792eeefb8f..3a26fb8c30 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,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. diff --git a/src/utils/openapi.ts b/src/utils/openapi.ts index 1d3a33c5f4..df2f91edce 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, From 2424cc5364bccf7c97acd1d089dd32bf98448f71 Mon Sep 17 00:00:00 2001 From: Alex Varchuk Date: Wed, 15 Jan 2025 16:09:19 +0100 Subject: [PATCH 2/8] docs: move options to deprecated section --- docs/config.md | 92 ++++++++++++++++++++++++++++++++- docs/redoc-vendor-extensions.md | 82 +++++++++++++++++++++++++++++ 2 files changed, 173 insertions(+), 1 deletion(-) diff --git a/docs/config.md b/docs/config.md index 6f1f477e56..a469d49042 100644 --- a/docs/config.md +++ b/docs/config.md @@ -82,8 +82,98 @@ Shows specification extensions ('x-' fields). Extensions used by Redoc are ignor If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS. -## Theme settings +## Deprecated Functional settings + +### 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`. + +### 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 + +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 diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 3a26fb8c30..792eeefb8f 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.md @@ -10,6 +10,9 @@ 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) @@ -36,6 +39,9 @@ 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) @@ -99,6 +105,29 @@ 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/) @@ -261,6 +290,59 @@ 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. From 3760bd65b98e5cc6fce26d2b6148b6172f548a67 Mon Sep 17 00:00:00 2001 From: Alex Varchuk Date: Wed, 15 Jan 2025 16:38:02 +0100 Subject: [PATCH 3/8] docs: improve documantation --- docs/config.md | 35 +++++++++++++++++++++++++++++------ docs/index.md | 2 +- 2 files changed, 30 insertions(+), 7 deletions(-) diff --git a/docs/config.md b/docs/config.md index a469d49042..47229823de 100644 --- a/docs/config.md +++ b/docs/config.md @@ -26,7 +26,7 @@ Sets the minimum amount of characters that need to be typed into the search dial _Default: 3_ -### 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. @@ -42,7 +42,7 @@ Hides the schema title next to to the type. 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. @@ -56,13 +56,13 @@ Displays only the specified number of enum values. The remaining values are hidd Shows only required fields in request samples. -### 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 @@ -82,8 +82,31 @@ Shows specification extensions ('x-' fields). Extensions used by Redoc are ignor 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. + ## 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. + +### 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. @@ -168,7 +191,7 @@ 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. diff --git a/docs/index.md b/docs/index.md index a98776c210..6e2716e8e1 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: From 435693451456b281643bc6b3170357ae9126b4da Mon Sep 17 00:00:00 2001 From: Alex Varchuk Date: Wed, 15 Jan 2025 17:09:13 +0100 Subject: [PATCH 4/8] docs: move downloadFileName and downloadDefinitionUrl to deprecated options --- docs/config.md | 8 ++++ docs/redoc-vendor-extensions.md | 82 --------------------------------- 2 files changed, 8 insertions(+), 82 deletions(-) diff --git a/docs/config.md b/docs/config.md index 47229823de..b7bc0982a5 100644 --- a/docs/config.md +++ b/docs/config.md @@ -92,6 +92,14 @@ Set the URLs used to download the OpenAPI description or other documentation rel 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. diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 792eeefb8f..3a26fb8c30 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,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. From abfb3244ab73ba308e2f69731f0357f316e3dabe Mon Sep 17 00:00:00 2001 From: Alex Varchuk Date: Tue, 21 Jan 2025 12:20:38 +0100 Subject: [PATCH 5/8] chore: add docs --- docs/config.md | 16 +++++++++++++++- docs/redoc-vendor-extensions.md | 33 ++++++++++++++++++++++++++++++++- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/docs/config.md b/docs/config.md index b7bc0982a5..ec8392106e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -82,10 +82,24 @@ Shows specification extensions ('x-' fields). Extensions used by Redoc are ignor If set to `true`, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS. -# downloadUrls +### 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 diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 3a26fb8c30..7721bb4bf6 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.md @@ -42,12 +42,15 @@ You can use the following [vendor extensions](https://redocly.com/docs/openapi-v - [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 @@ -320,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-explicitMappingOnly 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 +``` From 0f1a0eb6aade41708c0f33d98f198311fcab7aee Mon Sep 17 00:00:00 2001 From: Alex Varchuk Date: Tue, 21 Jan 2025 12:27:39 +0100 Subject: [PATCH 6/8] chore: fix problem inside documentation --- docs/config.md | 2 +- docs/redoc-vendor-extensions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/config.md b/docs/config.md index ec8392106e..c63940fc8f 100644 --- a/docs/config.md +++ b/docs/config.md @@ -218,7 +218,7 @@ _Default: false_ 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 **. +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 diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 7721bb4bf6..9ed239cef8 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.md @@ -334,7 +334,7 @@ The enum (short for "enumeration") fields in OpenAPI allow you to restrict the v 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-explicitMappingOnly example +#### 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 From dc11a64c3ae866ab1210a07fccedb8e805084329 Mon Sep 17 00:00:00 2001 From: Alex Varchuk Date: Tue, 21 Jan 2025 18:22:51 +0100 Subject: [PATCH 7/8] chore: remove html template option --- docs/config.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/config.md b/docs/config.md index c63940fc8f..59a16cb822 100644 --- a/docs/config.md +++ b/docs/config.md @@ -38,10 +38,6 @@ Hides the loading animation. Does not apply to CLI or Workflows-rendered docs. Hides the schema title next to to the type. -### htmlTemplate - -Sets the path to the optional HTML file used to modify the layout of the reference docs page. - ### 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. From 8b58fe9a04e478ee8e622e489b4d913b0edb2560 Mon Sep 17 00:00:00 2001 From: Alex Varchuk Date: Wed, 22 Jan 2025 12:56:42 +0200 Subject: [PATCH 8/8] chore: update docs/config.md Co-authored-by: Adam Altman --- docs/config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config.md b/docs/config.md index 59a16cb822..2e350253da 100644 --- a/docs/config.md +++ b/docs/config.md @@ -214,7 +214,7 @@ _Default: false_ 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**. +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