API Specificity with Overlays and Enums

The more I work on API standards, the more I realise how few teams understand that they can adopt the standards and, without breaking any contract, adapt them to make a strong interface for their own application. One of my favourite examples is to add enums where a standard interface cannot dictate the exact values, but in your own implementation it is very helpful to do so. Continue reading

Save edits to OpenAPI as an Overlay

For teams that generate OpenAPI from their codebase, there’s a tough choice between maintaining rich and extensive content such as Markdown descriptions and examples in codebase annotations, or in making those changes to the generated file – and then losing them when the code changes and the file is regenerated. The new OpenAPI Overlay Specification defines a format for storing updates to an OpenAPI document, and there’s a new generation of tools to make it easy to do, so let’s take a look. Continue reading