An OpenAPI extension adds custom data to an API definition through fields whose names begin with x-. Extensions can document organization-specific decisions or provide configuration that third-party tools use. API gateways may store declarative deployment settings directly in OpenAPI extensions, keeping them versioned alongside the API definition. section 4.4 section 1.5.5
Use extensions when the standard OpenAPI fields do not express an operational or governance requirement:
- Mark an exceptional departure from an API style guide and record why the exception is justified. section 5.5.9
- Supply tool-specific deployment configuration for gateways that interpret vendor extensions. section 1.5.5
- Control breaking-change analysis by recording lifecycle information such as an endpoint sunset date. section 4.4
Exclude a sunset endpoint from a breaking-change failure
Add x-sunset: "2022-08-30" to a deprecated GET /v1/catalog/categories operation, then run oasdiff breaking apiv1-dep.yaml apiv2.yaml. Because the date is in the past, oasdiff ignores the removed endpoint and reports no breaking change. Removing the extension causes the endpoint removal to be reported. section 4.4
paths:
/v1/catalog/categories:
get:
deprecated: true
x-sunset: "2022-08-30"
tags:
- Categories
summary: List all categories
Inspect the OpenAPI operation showing deprecated: true alongside an x-sunset date. section 4.4
