Tag Archives: openapi

28 Feb
2023

Improve Existing OpenAPI Descriptions

I’m a firm fan of a design-first approach to building APIs, and advocate for it at every opportunity. Repeatedly. Design-first means that an API change starts in the OpenAPI description, gets reviewed and approved by the stakeholders, and then gets built afterwards.

I also live in the real world, where OpenAPI descriptions get generated from existing codebases, and engineering teams lack either the knowledge or the enthusiasm to modernise their processes. With a generated OpenAPI description, everything else that OpenAPI enables is likely to be disappointing, because the description only contains the information that was in the serverside code, and if you’re lucky some comment metadata. Enter OpenAPI Overlays, a way to describe alterations to an existing OpenAPI description that can be reapplied every time that description changes. Continue reading →

14 Dec
2020

What’s New in OpenAPI 3.1

With OpenAPI 3.1 coming “soon”, I gave a talk at APIDays Paris about what to expect. But I’m a great fan of the written word as reference so here’s a written recap of what’s in the next OpenAPI release.

Top features:
– Compatible with JSON Schema 2020-12
– Webhook support
– Many other minor improvements
Continue reading →

06 Aug
2020

Creating a Simple OpenAPI Spec

Having API descriptions in your workflow is a game-changer, but how do you get from nothing to a functioning spec in the first place? I recently made a very simple spec for a very simple API, and thought it might make a good example for anyone looking to create a spec for the first time. OpenAPI specs are very verbose so this very tiny API makes quite a manageable example! Continue reading →
21 May
2020

Custom OpenAPI Style Rules with Spectral

Edit: There’s a newer post on this topic using Redocly CLI.

I work quite a bit with OpenAPI specs and with lots of specs and lots of collaborators, keeping the specs all functional (never mind tidy, consistent, or other dreamwords) is a challenge! We use spectral to check our specs, both when we work on them and in the build process. Spectral is great but it has Opinions(TM)!

For most users, running Spectral out of the box gives quite a lot of output even on an otherwise valid spec. I do think the default ruleset for Spectral is pretty good, but every situation is different so having your own ruleset to use is a good idea. This post shows how to use a ruleset and some examples. Continue reading →

18 Feb
2020

Teach Your API Test Platform to Send Callbacks

I already wrote about using Prism as an API test platform but I didn’t include an example with callbacks so this post is to fill that gap! If you didn’t read the previous post, the tl;dr is that Prism is a nodejs open source tool that can take your OpenAPI specification and then do an impression of your live API, validating the API calls sent to it and responding with the example data described in the spec. It can also follow up the API response and send an HTTP request of its own to mock the callbacks described in your OpenAPI spec. Continue reading →
23 Jan
2020

Instant Test API Platforms with Prism

I’ve been writing a bit about OpenAPI lately and I realised that I didn’t share how I’m creating local, test versions of production APIs to work with while I develop new client code or test SDK features. The recipe is simple: you will need an API spec, the excellent open source tool Prism and an HTTP client. Mix it up and be ready to change your API development workflows forever. Continue reading →
15 Aug
2019

OpenAPI Description using API key and secret

I’ve been working on a few OpenAPI descriptions of APIs lately, and really enjoying the benefits they bring. In particular the ability to import into Postman as a collection I think is a “killer feature” for APIs looking to get developers up and running quickly. The catch? I found that an API that needs an API key and secret, or a username and password/token, is supposed to be described with multiple security schemes – but this does not play nicely with tools like Postman. Continue reading →
26 Feb
2019

Using Tags in your OpenAPI Spec

Working with OpenAPI is bringing so many possibilities to the way that developers work with APIs, it’s exciting! The spec is very comprehensive though and I’ve found myself answering questions on individual aspects of it recently, so I thought I’d capture one or two of those things here. Today: tags. Continue reading →
08 Jan
2019

Ready-to-wear API Collections with OpenAPI and Postman

Have you noticed that API providers are starting to offer “descriptions” of their APIs? These are usually OpenAPI specifications, computer-readable documents that describe every aspect of an API’s endpoints. They can be used to generate documentation, SDKs, but now they can also be used for my favourite API-related activity: poking around! Postman just added a feature to allow importing OpenAPIs and I love it. Continue reading →
20 Nov
2018

Generating PHP library code from OpenAPI

I’m working with a bunch of OpenAPI specs now I am working for Nexmo and so far I’m loving working with API descriptions. OpenAPI is the next iteration of what used to be called “Swagger”, a machine-readable way to describe your API and from that description create docs, code libraries, tests, and all sorts. Today’s post is a quick writeup of how I generated some PHP code so that I can refer back to this next time I want to do it! Continue reading →