Design-first API Specification Workflow Matures
Written by Phil Sturgeon
/ Original link
on Mar. 1, 2018
Back in October I wrote Chasing the Perfect API Specification Workflow, which was a huge article about the state of the API specification world. One person trying to figure out a good workflow, in a sea of alternative specifications, with incomplete tooling, making it hard to see a solution for all the partial bits of functionality.
RAML and API Blueprint fell short of my requirements very quickly, and OpenAPI v3 was not available at the time of writing.
The initial requirements:
- API Design / Prototyping
- One source of truth where developers need to update stuff
- Beautiful documentation for humans built without any effort
- Validate payloads before you send em on the client side
- RSpec matchers providing contract testing API responses
- Documentation testing to confirm docs arent lies
- SDK Generators with customisable templates
OpenAPI v2.0 scored a 71% for those requirements, and the drastically improved (but frustratingly out of reach) OpenAPI v3.0 scored 86%. Tooling seemed very slow to move to OpenAPI v3, and a month after v3.0 was launched, pretty much nothing supported it.
JSON Schema divergence was huge, and with v2 missing oneOf, allOf, etc. it was difficult to write good specs for APIs with more "dynamic" contracts. At work we battled through the best we could, building as much documentation with OpenAPI v2 as possible. We actually did fairly well, but it was a stack of hacks and vendor extensions. It was painful to teach and depressing to use, but now, thankfully, we're on OpenAPI v3.0!!
OpenAPI v3.0
Right now my main goal has been generating human-readable documentation at the day job. With new employees starting every day, we need people to know how our many many many APIs work. Documentation is not the most interesting thing about API specifications by any means, but it's currently the most relevant at my job.
ReDoc was our documentation generator of choice, and it only supported v2.0 for a while. When the ReDoc 2.0.0 alpha builds started popping up supporting OpenAPI v3.0 we jumped on them, and helped discover a whole bunch of bugs. ReDoc author Roman Hotsiy was an absolute champion, fixing bugs and cutting alpha builds on a regular basis.
Thanks to ReDoc's use of swagger2openapi as a compatibility layer, OpenAPI v2/v3 are both supported. Our bevy of quirky API specs helped swagger2openapi author Mike Ralphson to isolate a bunch of bugs, and really test out the amazing new resolver logic in v2.12.0 betas. We have a build step that converts our OpenAPI v2 specs to v3 using 2.12.0-5, as ReDoc is still using 2.11.x and that's not quite so good at handling giant/self-referential schemas.
Certainly I'm not recommending you go screaming into using an alpha and a beta, but we are using these a whole bunch and have no more problems to report. If you want OpenAPI v3.0, give them a try.
Improving Specifications
A few months ago I came up with a medal system, to help give people an idea of where their docs/specs are at, and to give readers of the docs an idea of how much they could trust the docs.