OpenAPI and AsyncAPI allow specification extensions: custom fields that start with x- and that tools can interpret. This page lists the extensions Redoc CE reads and renders.
Redoc CE ignores all other extensions. The ignored extensions include the extensions that depend on the Redocly platform, such as x-rbac, x-seo, x-metadata, x-keywords, x-hideReplay, x-usePkce, and x-assertionType.
To display custom x- fields as plain text in the documentation, set the showExtensions option. With showExtensions: true, Redoc CE displays every extension it does not read itself and keeps the Redocly-only fields x-keywords, x-metadata, and x-usePkce hidden. To display Redocly-only fields, list them explicitly: showExtensions: ['x-seo', 'x-metadata'].
| Extension | Description |
|---|---|
| x-additionalPropertiesName | Display a field name for an additionalProperties description. |
| x-badges | Add visible badges to API operations. |
| x-codeSamples | Provide the code samples to display for an operation. Redoc CE displays these samples and the payload sample, and does not generate samples for other languages. A sample appears only when its label, or its lang when it has no label, is in the codeSamples language list. |
| x-displayName | Use a human-friendly display name for a tag. |
| x-enumDescriptions | Add readable labels for enum values. |
| x-explicitMappingOnly | Set on a schema with a discriminator to list only the schemas named in discriminator.mapping, and hide schemas matched implicitly. |
| x-logo | Display a logo at the top of the sidebar. Set info.x-logo with url (image URL), and optionally href (link target, defaults to info.contact.url), altText, and backgroundColor. |
| x-mcp | Document MCP servers and tools, and display the connect buttons on the overview page. |
| x-summary | Add a short summary of a response. |
| x-tagGroups | Group tags in the sidebar. |
| x-tags | Add individual schemas to navigation sections alongside operations. |
| x-traitTag | Mark tags that label operations instead of grouping them. |
| x-webhooks | Add webhooks to OpenAPI 3.0 and older descriptions. |
Redoc CE converts Swagger 2.0 descriptions to OpenAPI 3 before rendering, and reads the following extensions on the way:
- x-examples: add examples to a request, like the OpenAPI 3
exampleandexampleskeywords. - x-nullable: mark a schema as nullable.
- x-servers: add one or more target hosts for the API.
| Extension | Description |
|---|---|
| x-additionalPropertiesName | Display a field name for an additionalProperties description. |
| x-badges | Add visible badges to operations. |
| x-enumDescriptions | Add readable labels for enum values. |
| x-logo | Display a logo at the top of the sidebar, with the same info.x-logo fields as for OpenAPI. |
| x-tagGroups | Group tags in the sidebar. |
GraphQL schemas have no extension mechanism. Redoc CE renders the schema definition language as is, and takes the overview metadata from the info option.
Redoc CE 3.x ignores the <!-- Redoc-Inject: <security-definitions> --> comment that Redoc CE 2.x used to place the security schemes section in info.description. Instead, each operation displays its security requirements through a View security details action. You can remove the comment from info.description.
- OpenAPI extensions - Detailed reference for every extension, including examples
- AsyncAPI extensions - Detailed reference for the AsyncAPI extensions
- Configure Redoc CE - Display custom extensions with
showExtensions, and see every other option - Migration from Redoc CE 2.x to 3.x - Other changes between the versions