From The Blog

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

Run GitHub Actions on Subdirectories

I come across a lot of “greedy” GitHub Actions, where automation is running across a whole project instead of only on the parts that are relevant. Examples might be code linters that report problems with documentation folders, or the inverse of that. It’s especially problematic in monorepos where we probably want to use the same tool when we’re doing the same task for different subfolders, but that tool might not make sense to run everywhere. Continue reading

OpenAPI Overlays to avoid API oversharing

Most APIs aren’t perfect. By design they are long-lived and may serve many audiences. I see a lot of organisations maintaining multiple versions of APIs, or simply not documenting some of the endpoints to avoid them being included in the published documentation and confusing users. The problem of API redaction is a real one in most organisations, and it goes unsolved or is solved in a way that causes ongoing friction. I’ve helped a few API projects to solve this problem with the new OpenAPI Overlay specification so I thought I’d share! Continue reading

Talks, Articles, Podcasts, and More

Article

API Evangelist Conversation: Overlays


API Evangelist Conversation, December 2024
Video

API Evangelist Conversation: Redocly CLI


API Evangelist Conversation, October 2024
Slides

DevOps Your Docs


WriteTheDocs Atlantic, September 2024
Slides

API Description Pipelines


APIDays London, September 2024
Slides

AsyncAPI governance the easy way


APIDays London, September 2024