Working on API tools, I get to see inside lots of different organisations’ API projects and processes. Every scenario is different, but a common theme is that many companies use a more complicated API description workflow than you see in conference slide decks! Without sharing any one organisation’s secrets, this article shares a rundown of some typical steps that might show up in an API description pipeline.

Gather the inputs

If you’re publishing one API that draws on multiple sources, such as a set of microservices, it helps to combine those OpenAPI descriptions into one unified OpenAPI description. This is different to the bundling/dereferencing step that we’ll come to later.

If you’re publishing multiple APIs, then you’ll run all the steps here for each of the APIs. If you’re publishing one API (in various forms) to multiple sources, we’ll fan out to the different destinations part way through the pipeline.

Make, do, and mend

Wave the magic wand and improve the OpenAPI to add in everything that you’ll need in later stages. Typically this could include:

• finishing the developer experience by adding summaries, descriptions (for operations, tags, parameters, schemas … everything) and examples.
• adding metadata such as servers, info descriptions, licenses, docs platform links, and other items that either weren’t included or which need adding to the newly-assembled API description.
• fixing things that the generator did wrong (generators make invalid output more often than I realised until I started working a lot with this stuff).

OpenAPI is much richer than any of the possible information sources, or any individual output. For design-first organisations, all the extra goodness is there by design, but for teams working with API descriptions generated from code, or otherwise find themselves working with wish-this-was-better API descriptions, using tools to programmatically patch improvements is a winning game plan. It’s important to have a repeatable way of making these changes, since the OpenAPI inputs will update and it’s likely that will happen often.

Tools to try: OpenAPI Overlays or Redocly decorators.

Traditional CI checks

Every API needs this step as a minimum! Check that the OpenAPI description is valid, and optionally apply some formatting rules to check that quotes, line wrapping, indentation and that sort of thing are all as you would want them. You could even lint the Markdown in your OpenAPI description or sort entries into alphabetical order.

API governance rules are applied at this point. Governance and linting are a whole separate post (and I write a lot about this in my day job for Redocly since they make excellent tools for these things) so I’m restraining myself from that particular tangent. TL;DR make sure the API is up to scratch before you proceed. If it is not, then stop and try again.

Tools to try: Redocly lint or Spectral.

Performance interval

This is “half time” in the game of API description pipelines. All the inputs are in, counted, tidied up and verified. Now we can use the API descriptions to achieve our goals!

Endpoint censorship

Your work-in-progress APIs may include more information than you necessarily want to publish to all users of an API, so the next stage is to weed out things that shouldn’t be included. It’s common to run this step and all following steps in parallel, once for each deliverable thing or destination of an API description.

For example, you might remove all the endpoints with deprecated: true, or create an API description that only includes the endpoints tagged “partner”. This step is important otherwise you can find yourself maintaining a lot of different API descriptions that sort of overlap, or not being able to have API descriptions for things you’re actually working on because they can’t be published yet.

Tools to try: OpenAPI Overlays or Redocly decorators. And if you end up with tags that have no endpoints, there’s a recipe for that.

More metadata

The API description may be going to a few different destinations, and each one might need some different additions. For example, maybe your documentation renderer doesn’t understand multiple tags for one endpoint, so you strip the others at this point. Or the SDK generator you use gives better results if you add some extensions to the OpenAPI description before passing the API description to that tool.

Tools to try: OpenAPI Overlays or Redocly decorators. Yes, again.

Packaged up with a bow

Some of the destination tools in the OpenAPI space (meaning there are no further uses of the OpenAPI description after that tool) such as API Gateways may feature limited capacity to resolve references. Some don’t resolve external files and must be supplied a single-file OpenAPI description, in which case you can bundle yours and send that. Others can’t follow the OpenAPI $ref syntax at all, so look for a bundler than can “dereference” – meaning it puts everything inline, which can make for very large OpenAPI description files so do take care.

Tools to try: Redocly bundle.

Designing pipelines

If every API project needed the same tools in the same order, you’d be able to add it with a single click! In fact, every API and organisation are different, and so are their pipelines. I’ve outlined some common patterns in this article, so start with the “Traditional CI checks” step, and then pick from the other items on the list as you need them. As always, OpenAPI tooling moves quickly and there’s some good innovations in this space, so when you’re ready to add a new tool to the box it’s always worth a visit to https://openapi.tools/ and see what’s new or what best fits your requirements.

So, what’s missing from my list? Add a comment and let me know!