OpenAPI Extensions

Extensions (also referred to as specification extensions or vendor extensions) are custom properties that start with x-, such as x-logo. These are used to add extra information or functionality that the OpenAPI standard doesn’t include by default. For example, many tools including Amazon API Gateway, ReDoc, APIMatic, and Fern use extensions to include details specific to their products.

Adding Extensions

Extensions are supported on the root level of the API spec and in the following places:

info section
paths section, individual paths and operations
operation parameters
responses
tags
security schemes

The extension value can be a primitive, an array, an object or null. If the value is an object or array of objects, the object’s property names do not need to start with x-.

Example

An API that uses Amazon API Gateway custom authorizer might include extensions similar to this:

1
components:
2
  securitySchemes:
3
    APIGatewayAuthorizer:
4
      type: apiKey
5
      name: Authorization
6
      in: header
7
      x-amazon-apigateway-authtype: oauth2
8
      x-amazon-apigateway-authorizer:
9
        type: token
10
        authorizerUri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations
11
        authorizerCredentials: arn:aws:iam::account-id:role
12
        identityValidationExpression: "^x-[a-z]+"
13
        authorizerResultTtlInSeconds: 60

Did not find what you were looking for? Ask the community
Found a mistake? Let us know