docs: move options to deprecated section

2025-04-19 16:22:05 +03:00 · 2025-01-15 16:09:19 +01:00 · 2025-01-15 16:09:19 +01:00 · 2424cc5364
commit 2424cc5364
parent 38e109e7f4
2 changed files with 173 additions and 1 deletions
--- 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
--- 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.