# Redoc CE specification extensions

OpenAPI and AsyncAPI allow [specification extensions](https://spec.openapis.org/oas/v3.1.0#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`](/docs/redoc/v3.x/config#openapi-options) 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']`.

## OpenAPI extensions

| Extension | Description |
| --- | --- |
| [x-additionalPropertiesName](/docs/realm/content/api-docs/openapi-extensions/x-additional-properties-name) | Display a field name for an `additionalProperties` description. |
| [x-badges](/docs/realm/content/api-docs/openapi-extensions/x-badges) | Add visible badges to API operations. |
| [x-codeSamples](/docs/realm/content/api-docs/openapi-extensions/x-code-samples) | 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`](/docs/redoc/v3.x/config#other-options) language list. |
| [x-displayName](/docs/realm/content/api-docs/openapi-extensions/x-display-name) | Use a human-friendly display name for a tag. |
| [x-enumDescriptions](/docs/realm/content/api-docs/openapi-extensions/x-enum-descriptions) | 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](/docs/realm/content/api-docs/openapi-extensions/x-mcp) | Document MCP servers and tools, and display the connect buttons on the overview page. |
| [x-summary](/docs/realm/content/api-docs/openapi-extensions/x-summary) | Add a short summary of a response. |
| [x-tagGroups](/docs/realm/content/api-docs/openapi-extensions/x-tag-groups) | Group tags in the sidebar. |
| [x-tags](/docs/realm/content/api-docs/openapi-extensions/x-tags) | Add individual schemas to navigation sections alongside operations. |
| [x-traitTag](/docs/realm/content/api-docs/openapi-extensions/x-trait-tag) | Mark tags that label operations instead of grouping them. |
| [x-webhooks](/docs/realm/content/api-docs/openapi-extensions/x-webhooks) | Add webhooks to OpenAPI 3.0 and older descriptions. |

### Swagger 2.0 extensions

Redoc CE converts Swagger 2.0 descriptions to OpenAPI 3 before rendering, and reads the following extensions on the way:

- [x-examples](/docs/realm/content/api-docs/openapi-extensions/x-examples): add examples to a request, like the OpenAPI 3 `example` and `examples` keywords.
- [x-nullable](/docs/realm/content/api-docs/openapi-extensions/x-nullable): mark a schema as nullable.
- [x-servers](/docs/realm/content/api-docs/openapi-extensions/x-servers): add one or more target hosts for the API.

## AsyncAPI extensions

| Extension | Description |
| --- | --- |
| [x-additionalPropertiesName](/docs/realm/content/api-docs/asyncapi-extensions/x-additional-properties-name) | Display a field name for an `additionalProperties` description. |
| [x-badges](/docs/realm/content/api-docs/asyncapi-extensions/x-badges) | Add visible badges to operations. |
| [x-enumDescriptions](/docs/realm/content/api-docs/asyncapi-extensions/x-enum-descriptions) | 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](/docs/realm/content/api-docs/asyncapi-extensions/x-tag-groups) | Group tags in the sidebar. |

## GraphQL

GraphQL schemas have no extension mechanism.
Redoc CE renders the schema definition language as is, and takes the overview metadata from the [`info` option](/docs/redoc/v3.x/config#graphql-options).

## Security definitions injection

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`.

## Resources

- **[OpenAPI extensions](/docs/realm/content/api-docs/openapi-extensions)** - Detailed reference for every extension, including examples
- **[AsyncAPI extensions](/docs/realm/content/api-docs/asyncapi-extensions)** - Detailed reference for the AsyncAPI extensions
- **[Configure Redoc CE](/docs/redoc/v3.x/config)** - Display custom extensions with `showExtensions`, and see every other option
- **[Migration from Redoc CE 2.x to 3.x](/docs/redoc/v3.x/config-migration)** - Other changes between the versions