Common decisions about how-to OpenAPI
We've spoken with thousands of organizations that maintain OpenAPI definitions. These are common decisions we get consulted on, and you can see our general recommendations.
Code annotations vs. separate file(s)
Some people choose to generate their OpenAPI definitions from code annotations. The advantage is this keeps the definitions closer to the implementation server code. The disadvantage is it is typically more difficult to gain non-developer contributors such as the product team and technical writers. It also doesn't allow for a design-first workflow. In the case of annotations, the output will likely be a single bundled file. The quality of the file may vary based on your annotation tool.
Recommendation: separate files.
Single file vs. multi-file
If you maintain your definitions outside of the implementation code annotations, it's possible to leverage a multi-file format to help optimize for contributions. OpenAPI can be intimidating when viewed as a single file. If you view an OpenAPI file that was generated by a code annotation tool, they are often optimizing each line break and stuff the entire definition into a single line. This is not usable by a human. Even when "pretty printed" the output can be many thousands of lines and daunting to edit.
API creation and maintenance activities will affect the OpenAPI definition:
- Adding schema, a new operation or endpoint
- Deprecating or removing an operation
- Updating documentation of schema, operations or tags
- Adding or Updating examples
- Adding a new version of the API
It's much easier to do these activities with a multi-file structure.
The main drawback is some tooling doesn't support multi-file formats. Redocly offers automated bundling in our API Registry to solve this issue.
Recommendation: multi-file format
Storage in git vs. ________ vendor
Redocly loves docs-like-code. This means:
- Store your OpenAPI definitions in a version control (eg. git) repository.
- Use a workflow like the GitHub flow.
Your organization is already comfortable storing their source code in a version control repository such as GitHub.
Redocly offers an API registry to build bundled artifacts of your OpenAPI definitions.
Recommendation: git repository
JSON vs. YAML
YAML is more human-friendly. Especially given that OpenAPI supports markdown in descriptions and markdown is very hard to read or write within JSON.
YAML allows for multi-line markdown descriptions.
documentType: type: string description: | This is an example of a **multi-line** markdown description.
Git diffs will be smaller with YAML.
JSON is better for machines to read (many languages can parse JSON, whereas YAML more often requires a library to parse). Redocly offers bundling which can also convert your YAML definitions to a single JSON file.
Recommendation: use YAML