OpenAPI Extensions Overview
The APIMatic extensions you can add to an OpenAPI 3.x or Swagger 2.0 definition, and what APIMatic imports from each.
OpenAPI lets tools define their own properties, called specification extensions, whose names start with x-. APIMatic reads the extensions on these pages when it imports your OpenAPI 3.x or Swagger 2.0 definition. Use them to describe parts of your API that the standard can't, such as multiple environments, pagination, or webhook signature verification.
You add an extension next to the standard properties of the object it applies to:
openapi: 3.0.3
info:
title: Payments API
version: 1.0.0
x-server-configuration:
default-environment: production
default-server: default
environments:
- name: production
servers:
- name: default
url: https://api.example.comSupported extensions
| Extension | Applies to | Versions | What it does |
|---|---|---|---|
x-server-configuration | Info Object | 3.x, 2.0 | Defines environments, servers, and server URL parameters |
x-server-name | Operation Object | 3.x, 2.0 | Sets the server an endpoint calls |
x-additional-headers | Security Scheme Object | 3.x, 2.0 | Adds headers to every request |
x-rename-username-as, x-rename-password-as | Security Scheme Object | 3.x, 2.0 | Renames the Basic authentication credentials |
| OAuth 2.0 extensions | OAuth Flow Object (3.x), Security Scheme Object (2.0) | 3.x, 2.0 | Adds examples, client authentication options, token revocation, and default scopes |
x-security-options-meta | OpenAPI Object, Operation Object | 3.x, 2.0 | Names and describes each security option |
x-deprecation-details | Operation Object | 3.x, 2.0 | Adds a message and version to a deprecated endpoint |
x-unwrap-body | Operation Object | 3.x, 2.0 | Imports the properties of the request body as separate body parameters |
x-unique-name | Parameter Object | 3.x | Gives a parameter a different name in SDKs and docs |
x-example | Parameter Object | 2.0 | Adds an example value to a parameter |
x-pagination | Media Type Object of a response | 3.x | Describes how the endpoint paginates its results |
x-sse-sentinel | Media Type Object of a response | 3.x | Sets the value that ends a Server-Sent Events stream |
x-enum-elements | Schema Object, Parameter Object (2.0) | 3.x, 2.0 | Names and describes each enum value |
x-enum-model-name | Schema Object (3.x), Parameter Object (2.0) | 3.x, 2.0 | Sets the name of an enum model |
x-discriminator-value | Discriminator Object (3.x), Schema Object (2.0) | 3.x, 2.0 | Sets a custom discriminator value |
x-is-dynamic | Schema Object | 3.x, 2.0 | Imports a schema as a dynamic type |
x-exception-model-name | Schema Object | 3.x, 2.0 | Sets the name of the error model created from an error response |
x-webhooks, x-callbacks | OpenAPI Object | 3.x | Groups webhooks or callbacks, routes events, and verifies signatures |
x-webhook-group, x-callback-group | Operation Object of a webhook or callback | 3.x | Assigns a webhook or callback to a group |
x-image-uri | Info Object | 3.x, 2.0 | An absolute URL of an image for the API |
APIMatic also reads x-tags on parameters and schema properties to filter your definition. See Specify API Metadata.
Besides these extensions, APIMatic reads two custom values of the standard format property for date-time types. See Date-time formats.
Validation
APIMatic checks most of these extensions when it validates your definition, for example that a default server exists or that a pagination pointer references an existing property. The rules are listed with the rest of the OpenAPI rules in OpenAPI v3 APIMatic Linting, and the checks that run after import are in APIMatic CodeGen Validation. For how to change their severity, see Configure Validation.
Extensions for the v3 generator
APIMatic still reads x-codegen-settings and x-operation-settings, which carry settings for the v3 code generator, and the test case extensions such as x-unitTests and x-testValue, which drive SDK test generation. Codegen v4 doesn't use CodeGen settings or test generation, so these pages don't cover them.