I have been working hard to establish some sort of minimum viable definition for a complete Swagger definition is, and I think I finally have got to a point where I have it–at least enough to work through the next 100 or so APIs I’m targeting for completion.
I originally identified almost 30 separate questions specifically targeting Swagger, but for my minimum viable definition I’ve isolated it to just 19. I automated asking of these questions, using my Questions API, and to test things out I applied it to my API API:
API (APIs.json)
Is there a Swagger definition?
yes
Is there a Swagger API title?
yes
Is there a Swagger API description?
yes
Is there a Swagger API host?
yes
Is there a Swagger API base path?
yes
How many Swagger API paths are there?
24
Do all Swagger API paths have tags?
yes
Do all Swagger API paths have summary?
yes
Do all Swagger API paths have description?
yes
Do all Swagger API paths have operation id?
yes
Do all Swagger API paths have parameters?
yes
Do all Swagger API paths have responses?
yes
Do all Swagger API response have references to definitions?
yes
Does Swagger APIs have security definitions?
yes
Do all Swagger API paths have security references?
yes
Is there Swagger API definitions?
yes
Do all Swagger API definitions have properties?
yes
Do all Swagger API definition properties have a description?
yes
Do all Swagger API definition properties have a type?
yes
In theory, I can run this on any APIs.json file, and it will return answers for any API that has a valid Swagger file present. My goal is to provide me with a quick action todo list for any API in my API Stack.
Now I want some sort of way to certify that all these questions were asked, import the Swagger into Postman, or some other tool and actually execute a real call against each endpoint. I’m still evaluating how to record this information somewhere, so it can be verified at any time, but anyone.
Anyways, I have about 50 APis targeted for completion, using my new Questions API. I even created a simple little widget to ask the questions of each API, something I will automate as soon as possible, and build into my API stack.
