Everyone wants their OpenAPIs to be complete, but what that really means will depend on who you are, what your knowledge of OpenAPI is, as well as being driven by your motivation for having an OpenAPI in the first place. I wanted to take a crack at articulating a complete(enough) definition for OpenAPIs I create, based upon what I’m needing them to do.
Info & Base - Give the basic information I need to understand who is behind, and where I can access the API.
Paths - Provide an entry for every path that is available for an API, and should be included in this definition.
Parameters - Provide a complete list of all path, query, and header parameters that can be used as part of an API.
Descriptions - Flesh out descriptions for all the path and parameter descriptions, helping describe an API does.
Enums - Publish a list of all the enumerated values that are possible for each parameter used as part of an API.
Definitions - Document the underlying schema being returned by creating a JSON schema definition for the API.
Responses - Associate the definition for the API with the path using a response reference, connecting the dots regarding what will be returned.
Tags - Tag each path with a meaningful set of tags, describing what resources are available in short, concise terms and phrases.
Contacts - Provide contact information for whoever can answer questions about an API, and provide a URL to any support resources.
Create Security Definitions - Define the security for accessing the API, providing details on how each API request will be authenticated.
Apply Security Definitions - Apply the security definition to each individual path, associating common security definitions across all paths.
Complete(enough) - That should give us a complete (enough) API description.
Obviously there is more we can do to make an OpenAPI even more complete and precise as a business contract, hopefully speaking to both developers and business people. Having OpenAPI definitions are important, and having them be up to date, complete (enough), and useful is even more important. OpenAPIs provide much more than documentation for an API. They provide all the technical details an API consumer will need to successfully work with an API.
While there are obvious payoffs for having an OpenAPI, like being able to publish documentation, and generate code libraries. There are many other uses for an OpenAPI like loading into Postman, Stoplight, and many other API services and tooling that helps developers understand what an API does, and reduce friction when they integrate, and have to maintain their applications. Having an OpenAPI available is becoming a default mode of operation, and something every API provider should have.
