AsyncAPI extension: x-badges

Use the x-badges option to add badges to channels, operations, and schema fields as indicators in API documentation.

The badges are displayed in API reference documentation in the following locations:

Channels and operations:

• the title of a channel or an operation in the header of the page
• the channel or operation item when it displays in a navigation list

Schema fields: next to the property name in message payload and headers schemas, and in the property details.

Each object can have multiple badges, and the displayed color is also configurable.

Add an array of x-badges to any of the following:

• Channel object
• Operation object
• Schema object (message payload or headers, and properties within schemas in components/schemas or inline)

The following example sets a Beta badge on the User Ratings Topic channel:

asyncapi: 3.0.0
...
channels:
  ratings:
    address: ratings-{ratingDirection}
    title: User Ratings Topic
    summary: Event stream of driver and passenger ratings
    description: Topic for collecting and processing user experience ratings submitted by drivers and passengers.
    servers:
      - $ref: '#/servers/production'
    x-badges:
      - name: 'Beta'
        position: before
    messages:
      driverRating:
        $ref: '#/components/messages/driverRating'

You can add x-badges to any schema object, including properties within message payload or headers schemas:

components:
  schemas:
    OrderEvent:
      type: object
      properties:
        quantityFilled:
          type: integer
          description: Filled quantity (experimental).
          x-badges:
            - name: 'Experimental'
        status:
          type: string
          x-badges:
            - name: 'New'
              position: before
              color: green

When the schema is used as a message payload or headers, the badges appear next to each property name in the documentation.

• Supported AsyncAPI extensions - Complete list of all AsyncAPI extensions supported by Redocly for enhanced API documentation