Tag Archives: openapi

04 Dec
2025

Nested tags in OpenAPI 3.2

OpenAPI has always had support for simple tags, but the OpenAPI 3.2 release brought in some serious tag upgrades including a summary field, a “kind” field with registry, – and the ability to nest tags which is the focus of today’s post. If one level of organisation isn’t enough for your API (and on bigger APIs I’d argue it shouldn’t be) then the ability to indicate which tag is the parent of this tag will be a good feature to adopt when you upgrade your OpenAPI descriptions. Continue reading →
21 Jul
2025

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 →
26 Mar
2025

Right-Size Your RESTful API: More Flexibility Without GraphQL

If you publish a RESTful API and there are situations when you need less (or more!) detail in the API responses from your API – then this post is for you. When I run into this with the teams I advise, the initial problem statement usually arrives more like “We need to move to GraphQL”, but this is a solution, not a problem to solve. The problem usually turns out to be either or both of:

  • the API responses are simply too large for some of the clients or uses cases, users need to select just the fields they want
  • the API doesn’t have enough information in the response payload for this client or use case, users need to choose to include nested data

GraphQL is one way to achieve these things, but this post is about the RESTful way to provide the right level of detail in an API response. Continue reading →

12 Mar
2025

Markdown/Mermaid output for OpenAPI Arazzo

API reference documentation changed the way we built integrations, and eventually became part of the driving force for OpenAPI adoption and all the good tooling that flowed from it. As a developer experience specialist, I spend a lot of time thinking about how human users can work with the technical assets in a project. HTML-format API reference documentation does a great job of building that bridge when working on OpenAPI projects, but now I’m using Arazzo and it’s a very new standard with not nearly as many tools available for that format yet – so I built one. –
17 Feb
2025

From HTTP to OpenAPI with Optic

I’ve been using Optic’s CLI, an OpenAPI tool that does a bunch of things including diffing OpenAPI descriptions and comparing HTTP traffic with OpenAPI. My use case was an established API that didn’t have an OpenAPI file yet – using Optic we could create one as a starting point, and then move to a design-first workflow to make the changes that I was there to help with. For this blog post, I’ve used the example of https://api.joind.in as an excellent representation of an API still in use, but without an OpenAPI file and not built with code that a code generator would recognise. Continue reading →
14 Feb
2025

Preview OpenAPI as HTML using Scalar

The API DevTools space is alive and well with lots of new and exciting products popping up all the time. I’ve been especially impressed by the new tools in the docs space, but some of the options are less practical for use as quick human-friendly OpenAPI renderings or previews to use during API development. My current favourite in this space is Scalar because I can get an HTML file to easily include in a build or share with others. It’s a bit of a hack though, so I thought I’d share… Continue reading →
09 Jan
2025

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 →
12 Dec
2024

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 →
09 Oct
2024

Open Standards for APIs

I work or have worked with APIs of all sorts of standards, sometimes many standards at once – or none. Each standard exists for a purpose and might be a great fit, or a terrible fit for other purposes. Today’s post is a recap of some of the common API standards around and what you need to know about each one. Continue reading →
05 Aug
2024

Lint APIs with Redocly CLI

API governance needs good tooling, and rules that fit – so today’s post covers both.

Fun fact: I work at Redocly and had used the tool for years, but recently realised that I have a post about a different tool in the archives of my blog, but no Redocly post. So here’s the Lorna-recommended version of OpenAPI linting with Redocly CLI. Continue reading →