Skip to content

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

Section titled “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

Section titled “Example”

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

components:
  securitySchemes:
    APIGatewayAuthorizer:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: oauth2
      x-amazon-apigateway-authorizer:
        type: token
        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
        authorizerCredentials: arn:aws:iam::account-id:role
        identityValidationExpression: "^x-[a-z]+"
        authorizerResultTtlInSeconds: 60

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