Last updated 3 days ago

Redoc specification extensions

Redoc makes use of the following specification extensions (aka vendor extensions).

Important

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The extensions properties are implemented as patterned fields that are always prefixed by "x-"

OAS root/Swagger Object specification extensions

Extend OpenAPI root Swagger Object

x-servers

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

x-tagGroups

Field Name Type Description
x-tagGroups [ Tag Group Object ] A list of tag groups

Usage in Redoc

x-tagGroups is used to group tags in the side menu. If you are going to 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!

Tag group object

Information about tag groups.

Fixed fields
Field Name Type Description
name string The group name
tags [ string ] List of tags to include in this group

x-tagGroups example

JSONYAML
{
  "x-tagGroups": [
    {
      "name": "Customers",
      "tags": ["Customers", "Customer Authentication", "AML", "Tags", "Customers Timeline"]
    },
    {
      "name": "Payment Instruments",
      "tags": ["Payment Instruments", "Payment Tokens", "Payment Cards"]
    }
  ]
}
x-tagGroups:
  - name: Customers
    tags:
      - Customers
      - Customer Authentication
      - AML
      - Tags
      - Customers Timeline
  - name: Payment Instruments
    tags:
      - Payment Instruments
      - Payment Tokens
      - Payment Cards

Example

Rebilly API Reference documentation

x-ignoredHeaderParameters

Field Name Type Description
x-ignoredHeaderParameters [ string ] A list of ignored headers

Usage in Redoc

x-ignoredHeaderParameters is used to specify header parameter names which are ignored by Redoc

x-ignoredHeaderParameters example

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

x-webhooks

This extension adds support for webhooks which is added to OAS 3.1. In OAS 3.0 or 2.0 please use x-webhooks (because webhooks is not allowed with the extension namespace prefix).

This makes it possible to document webhooks the same way you document APIs and provides quick path to compatibility with OAS 3.1 (remove the x- prefix).

From the specification...

Field name Type Description
webhooks Map[string, Path Item Object | Reference Object] The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the callbacks feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An example is available.

The only difference between that an the extensions is the x- prefix to the field name (which becomes x-webhooks).

Usage in Redoc

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

x-additionalPropertiesName example

Player:
  required:
  - name

  properties:
    name:
      type: string

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

Info object specification extensions

Extends OpenAPI Info Object

Field Name Type Description
x-logo Logo Object The information about API logo

Usage in Redoc

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

Logo Object

The information about the API's logo.

Fixed fields
Field Name Type Description
url string The URL pointing to the spec logo. MUST be in the format of a URL. It SHOULD be an absolute URL so your API definition is usable from any location
backgroundColor string background color to be used. MUST be RGB color in [hexadecimal format] (https://en.wikipedia.org/wiki/Web_colors#Hex_triplet)
altText string Text to use for alt tag on the logo. Defaults to 'logo' if nothing is provided.
href string The URL pointing to the contact page. Default to 'info.contact.url' field of the OAS.

x-logo example

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

Example

Redoc PetStore Reference documentation

Tag object specification extensions

Extends OpenAPI Tag Object

x-traitTag

Field Name Type Description
x-traitTag boolean In Swagger two operations can have multiple tags. This property distinguishes between tags that are used to group operations (default) from tags that are used to mark operation with certain trait (true value)

Usage in Redoc

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

x-traitTag example

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

x-displayName

Field Name Type Description
x-displayName string Defines the text that is used for this tag in the menu and in section headings

Operation object specification extensions

Extends OpenAPI Operation Object

x-codeSamples

Field Name Type Description
x-codeSamples [ Code Sample Object ] A list of code samples associated with operation

Formerly known as x-code-samples.

Usage in Redoc

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

Code Sample Object

Operation code sample.

Fixed fields
Field Name Type Description
lang string Code sample language. Value should be one of the following list
label string Code sample label e.g. Node or Python2.7, optional, lang will be used by default
source string Code sample source code

Code sample object example

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

Example

Redoc PetStore Reference documentation

Parameter object specification extensions

Extends OpenAPI Parameter Object

x-examples

Field Name Type Description
x-examples Example Object Object that contains examples for the request. Applies when in is body and mime-type is application/json

Usage in Redoc

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

Example

Redoc PetStore Reference documentation

Response object specification extensions

Extends OpenAPI Response Object

x-summary

Field Name Type Description
x-summary string a short summary of the response

Usage in Redoc

If specified, x-summary is used as the response button text. Description is rendered under the button.

Schema Object specification extensions

Extends OpenAPI Schema Object

x-nullable

Field Name Type Description
x-nullable boolean marks schema as a nullable

Usage in 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

Usage in Redoc

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 which is 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

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 Redoc-specific vendor extension. It won't be supported by other tools.

Extends the additionalProperties property of the schema object.

Field Name Type Description
x-additionalPropertiesName string descriptive name of additional properties keys

Usage in Redoc

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

x-additionalPropertiesName example

Player:
  required:
  - name

  properties:
    name:
      type: string

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