Govern your APIs with Speccy

The last year has involved a lot of teaching engineers how to use OpenAPI, with the day job growing from a startup to a sizeable corporation. Our engineering department has exploded, with new engineers starting every day. On one hand OpenAPI has been embraced as our approach to designing and documenting APIs, but on the other hand very few engineers have had any experience with it. As such, getting them up to speed with how to efficiently write descriptive, readable, and concise OpenAPI definitions has been a sizeable challenge.

To meet that challenge, Speccy was created, with a huge amount of help from oas-kit author Mike Ralphson. It has many functions as an OpenAPI local development workflow assistant, but it primarily exists as a linter. As a linter, it can provide opinions, advice, and suggestions more than just “is this valid or not”. The advice moves into “You should add descriptions to your parameters so people know what they’re for” and “Add contact info so other folks know who to talk to when they need help”.

There are a whole bunch of rules for Speccy already, and they’re split across “default” and “strict” meaning you don’t need to use all of them. You can provide arguments via --skip="contact-properties,license-url" if any specific rules are rubbing you up the wrong way.

What Speccy really needs, is a lot more rules.

Here are some I thought up at work recently:

• No need to provide both example and default, when they contain the same value
• No need to provide enum: [true, false] for a type: boolean

I want to introduce a more file-level set of validaiton rules too, maybe under speccy doctor openapi.yaml to keep it away from the more object-level linter:

• This file is 12824 lines long and does not contain a single $ref
• No links are used anywhere in this file, how will people know that a response is somehow connected to another response?

Kin Lane wrote about the future of Speccy a while back, in An OpenAPI-Driven, API Governance Rules Engine.

My only feedback right now, is that we need lots of people using it, and helping contribute rules. Oh, and wrap it in an API, and make it available as an easy to use, and deploy containerized microservice. Then lets get to work on the Github Gist-driven marketplace of rules, where I can publish the rules I develop across the projects I’m working on, and of the clients I consult with. Let’s get to work making sure there are a wealth of rules, broken down into different categories for API providers to choose from. Then let’s get API tooling and service providers to begin baking a Speccy rules engine into their solutions, and allow for the import and management of open source rules.

All of that is on the to-do list. An API will exist soon, and was one of the multiple products of a recent hackathon. I’ll get it cleaned up and out on speccy.io at some point. As far as a rules marketplace goes, that’s a while off. For now, how about you folks get in the comments, Twitter, or Slack, with suggestions for rules that you’d like to see.

Pull requests are also very welcome!