{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"openapi-extension-x-badges","__idx":0},"children":["OpenAPI extension: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-badges"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-badges"]}," option to add badges to channels, operations, and schema fields as indicators in API documentation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The badges are displayed in API reference documentation in the following locations:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Operations:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the title of an operation in the header of the page"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the operation item when it displays in a navigation list"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Parameters:"]}," next to the parameter name in the parameters list and in the parameter details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Schema properties:"]}," next to the property name in request/response body schemas and in the property details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each object can have multiple badges, and the displayed color is also configurable."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"location","__idx":1},"children":["Location"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add an array of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-badges"]}," to any of the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Operation object (under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths.<path>.<method>"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parameter object (operation parameters or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components/parameters"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Schema object (including properties under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema.properties"]}," in components or inline)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":2},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["x-badges"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[ ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#badge-object"},"children":["Badge Object"]}," ]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A list of badges."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"badge-object","__idx":3},"children":["Badge Object"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED"]},"."," ","The text that displays in the badge."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["color"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The color of the badge."," ","Supports predefined color names for consistent styling or direct color values for custom backgrounds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Supported color names:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["red"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["green"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blue"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grey"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["turquoise"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["magenta"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purple"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrot"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["raspberry"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orange"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grass"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["persian-green"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sky"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blueberry"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Supported status colors:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warning"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["default"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approved"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grey"]},"."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["position"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The position of the badge relative to the label text."," ","Possible values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["before"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["after"]},"."," ","Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["after"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example sets a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Beta"]}," badge on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Get special event"]}," operation:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"museum.yaml","header":{"title":"museum.yaml","controls":{"copy":{}}},"source":"openapi: 3.1.0\n...\npaths:\n  /special-events/{eventId}:\n    get:\n      summary: Get special event\n      description: Get details about a special event.\n      operationId: getSpecialEvent\n      tags:\n        - Events\n      parameters:\n        - $ref: '#/components/parameters/EventId'\n      x-badges:\n        - name: 'Beta'\n          position: before\n      responses:\n        '200':\n          description: Success.\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/SpecialEventResponse'\n              examples:\n                default_example:\n                  $ref: '#/components/examples/GetSpecialEventResponseExample'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/x-badges-eb955e1db29fa4e5.png","alt":"Image of sample OpenAPI definition with badges displayed","framed":true,"withLightbox":true},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parameter-with-badges","__idx":5},"children":["Parameter with badges"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-badges"]}," to a parameter (inline or in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components/parameters"]},"):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n  parameters:\n    ExperimentalFlag:\n      name: experimentalFlag\n      in: query\n      schema:\n        type: boolean\n      x-badges:\n        - name: 'Experimental'\n          position: after\n        - name: 'Beta'\n          position: before\n          color: blue\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"schema-property-with-badges","__idx":6},"children":["Schema property with badges"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-badges"]}," to any schema object, including properties within a schema:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n  schemas:\n    OrderResponse:\n      type: object\n      properties:\n        quantityFilled:\n          type: integer\n          description: Filled quantity (experimental).\n          x-badges:\n            - name: 'Experimental'\n        status:\n          type: string\n          x-badges:\n            - name: 'New'\n              position: before\n              color: green\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":7},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/openapi/show-extensions"},"children":["Show extensions configuration"]}]}," - Control which extensions are included in your API reference documentation for optimal presentation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/openapi"},"children":["OpenAPI configuration settings"]}]}," - Complete reference for all available OpenAPI configuration options and customization settings"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/api-docs/openapi-extensions"},"children":["Supported OpenAPI extensions"]}]}," - Complete list of all OpenAPI extensions supported by Redocly for enhanced API documentation"]}]}]},"frontmatter":{},"tagList":["img","table"],"title":"OpenAPI extension: x-badges","lastModified":"2026-09-17T13:26:51.000Z"}