API-51: Publish OAS document at a standard location in JSON-format
API-51: Publish OAS document at a standard location in JSON-format
To make the OAS document easy to find and to facilitate self-discovering clients, there should be one standard location where the OAS document is available for download. Clients (such as Swagger UI or ReDoc) must be able to retrieve the document without having to authenticate. Furthermore, the CORS policy for this URI must allow external domains to read the documentation from a browser environment.
The standard location for the OAS document is a URI called openapi.json or openapi.yaml within the base path of the API. This can be convenient, because OAS document updates can easily become part of the CI/CD process.
At least the JSON format must be supported. When having multiple (major) versions of an API, every API should provide its own OAS document(s).
An API having base path https://api.example.org/v1/ must publish the OAS document at:
https://api.example.org/v1/openapi.json
Optionally, the same OAS document may be provided in YAML format: