You can use the following vendor extensions with Redoc.

• Swagger Object
  • x-servers
  • x-tagGroups
  • Tag Group Object
  • x-ignoredHeaderParameters
• Info Object
  • x-logo
  • Logo Object
• Tag Object
  • x-traitTag
  • x-displayName
• Operation Object
  • x-codeSamples
  • Code Sample Object
• Parameter Object
  • x-examples
• Response Object vendor extensions
  • x-summary
• Schema Object
  • x-nullable
  • x-extendedDiscriminator
  • x-additionalPropertiesName
  • x-explicitMappingOnly

Extends the OpenAPI root OpenAPI Object

Backported from OpenAPI 3.0 servers. Currently doesn't support templates.

x-tagGroups is used to group tags in the side menu. Before you use x-tagGroups, make sure you add all tags to a group, since a tag that is not in a group, will not be displayed at all!

Information about tags group

json

{
  "x-tagGroups": [
    {
      "name": "User Management",
      "tags": ["Users", "API keys", "Admin"]
    },
    {
      "name": "Statistics",
      "tags": ["Main Stats", "Secondary Stats"]
    }
  ]
}

yaml

x-tagGroups:
  - name: User Management
    tags:
      - Users
      - API keys
      - Admin
  - name: Statistics
    tags:
      - Main Stats
      - Secondary Stats

Use x-ignoredHeaderParameters to specify header parameter names which are ignored by ReDoc.

swagger: '2.0'
info:
  ...
tags: [...]
x-ignoredHeaderParameters:
  - Accept
  - User-Agent
  - X-Test-Header

Extends the OpenAPI Info Object

x-logo is used to specify API logo. The corresponding image is displayed just above the side-menu.

The information about API logo

json

{
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "x-logo": {
      "url": "https://redocly.github.io/redoc/petstore-logo.png",
      "backgroundColor": "#FFFFFF",
      "altText": "Petstore logo"
    }
  }
}

yaml

info:
  version: "1.0.0"
  title: "Swagger Petstore"
  x-logo:
    url: "https://redocly.github.io/redoc/petstore-logo.png"
    backgroundColor: "#FFFFFF"
    altText: "Petstore logo"

Extends the OpenAPI Tag Object

Tags that have x-traitTag set to true are listed in the side-menu but don't have any subitems (operations). It also renders the description tag. This is useful for handling out common things like Pagination, Rate-Limits, etc.

json

{
    "name": "Pagination",
    "description": "Pagination description (can use markdown syntax)",
    "x-traitTag": true
}

yaml

name: Pagination
description: Pagination description (can use markdown syntax)
x-traitTag: true

Extends the OpenAPI Operation Object

x-codeSamples are rendered on the right panel in Redoc.

Operation code sample

json

{
  "lang": "JavaScript",
  "source": "console.log('Hello World');"
}

yaml

lang: JavaScript
source: console.log('Hello World');

Extends the OpenAPI Parameter Object

x-examples are rendered in the JSON tab on the right panel in Redoc.

Extends the OpenAPI Response Object

If specified, you can use x-summary as the response button text, with description rendered under the button.

Extends the OpenAPI Schema Object

Schemas marked as x-nullable are marked in Redoc with the label Nullable

ATTENTION: This is a Redoc-specific vendor extension, and is not supported by other tools.

Redoc uses this vendor extension to solve name-clash issues with the standard discriminator. Value of this field specifies the field which will be used as a 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.

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.

ATTENTION: This is a Redoc-specific vendor extension, and is not supported by other tools.

Extends the additionalProperties property of the schema object.

Redoc uses this extension to display a more descriptive property name in objects with additionalProperties when viewing the property list with an object.

Player:
  required:
  - name

  properties:
    name:
      type: string

  additionalProperties:
    x-additionalPropertiesName: attribute-name
    type: string

ATTENTION: This is Redoc-specific vendor extension, and is not supported by other tools.

Extends the discriminator property of the schema object.

Redoc uses this extension to filter the discriminator mappings shown in the selectpicker. When set to true, the selectpicker will only list the the explicitly defined mappings. When false, the default behavior is kept, i.e. explicit and implicit mappings will be shown.

Pet:
  type: object
  required:
    - name
    - photoUrls
  discriminator:
    propertyName: petType
    x-explicitMappingOnly: true
    mapping:
      cat: "#/components/schemas/Cat"
      bee: "#/components/schemas/HoneyBee"

Will show in the selectpicker only the items cat and bee, even though the Dog class inherits from the Pet class.