We were working on a new API last night and before we got too far along in our work we wanted to run our design by the OpenAPI Doctor. The first diagnosis hurt a bit, and felt like the first visit back to the doctor after avoiding them and drinking and eating all the things we know we aren’t supposed to. Our OpenAPI came in at a scorching 10% failure rate, which was worse than we anticipated, but we knew that we were just getting started.
We kept coming back thinking we had solved everything, but alas we didn’t have descriptions and some of our copy / paste efforts weren’t good enough for the Doctor. But eventually we did enough work to get things up to an A+ by the doctor’s standards, leaving us feeling like we were ready to begin sharing with other stakeholders.
The OpenAPI Doctor goes a bit further than we normally do with some of our rules, but that is OK–we also have some rules that the OpenAPI Doctor doesn’t govern. What we really liked was the blend of rules plus JSON Schema validation, which we believe is the most important blend of API governance that people tend to forget as the double down on using governance rules. Oh, did I mention that everything returned by the OpenAPI Doctors was fast? There is no time delay in a Vacuum!
This work settles it. All APIs go to the OpenAPI Doctor before they are shown to any other stakeholders or begin any coding. We had actually started coding a couple of the operations, but quickly hit pause after getting an unfavorable diagnosis from the OpenAPI Doctor. We aren’t design-first or code-first around here, we are a Frankenstein blend of the two. The OpenAPI Doctor is the best OpenAPI editor out there not just because of the editor, explorer, and documentation, but also their approach to baking governance rules and schema validation into the process and providing such a rich feedback loop on the design of your API-—which is configurable and adjustable using the rules tab and the completeness of the schema for your API.
