Context and Problem Statement
We have our API specification docs in two different formats: Swagger 2.0 and OpenAPI 3.0.
As of this writing, the split is roughly 50/50 between these two formats.
Notably, “Swagger” has been renamed to “OpenAPI”…i.e. OpenAPI 3.0 is the next major version of the Swagger specification.
The ideal state is to have all of our API spec docs in a single, consistent format.
Decision Drivers
- Consistency for API developers
- Consistency for API consumers
- Tooling compatibility
- Feature capability within the spec
Decision Outcome
Chosen option: Standardize and convert to OpenAPI 3.0
Considered Options
- Standardize and convert to OpenAPI 3.0
- Leave things as they currently exist
- Let folks decide on a case-by-case basis
Pros and Cons of the Options
Standardize and convert to OpenAPI 3.0
- Good, because it is the most up-to-date spec format with supported tooling
- Good, because it offers capabilities necessary to fully describe our API
- Good, because roughly half of our existing specs are in this format
- Bad, because it requires conversion of roughly 28 spec files
- Bad, because it requires some coordination of the conversion effort
Leave things as they currently exist
- Good, because this does not require anyone to do any work right now
- Bad, because this limits how API developers can describe our API in the spec
- Bad, because this leaves API consumers with the work of having to juggle two different spec formats
Let folks decide on a case-by-case basis
- Good, because the ’non-decision’ decision means that conversion work only has to be picked up if someone wants to do it
- Bad, because this causes an extra decision for API developers to have to make
- Bad, because this causes extra churn in Pull Requests if other API developers disagree with the selected format
- Bad, because this likely leaves API consumers with the work of having to juggle two different spec format