docs: update options for future major release (#2646)

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

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
+### hideDownloadButtons
-
-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
+### jsonSamplesExpandLevel
-
-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
 
 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
+### sortRequiredPropsFirst
-
-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.
 
-### 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
 
 

docs/index.md

@@ -67,7 +67,7 @@ theme:
   openapi:
     disableSearch: true
     expandResponses: 200,202
-    jsonSampleExpandLevel: 1
+    jsonSamplesExpandLevel: 1
 
     theme:
       sidebar:

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
+```

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,