17 Optimizing an OpenAPI document
This chapter covers
- Defining consistent elements with JSON Schema and OpenAPI
- Sharing components across OpenAPI documents
- Defining OpenAPI guidelines
We may have hesitated between an integer and a string when modeling a product ID and used one or the other in various path and query parameters or properties in body data models in our OpenAPI document. We will need to update each instance of the many 500 errors if we intend to add an Error-Id response header after describing numerous operations.
Authoring OpenAPI documents can lead to cumbersome information duplication and, more worryingly, API design inconsistency. Additionally, unoptimized OpenAPI documents that don’t use all of the format’s possibilities are more complex to author and maintain, leading to more inconsistencies. By using OpenAPI and JSON Schema extensively, we can optimize our OpenAPI documents to reduce the risk of inconsistencies and facilitate our work. That must be done separately from the first pass through the design so we don’t mix design- and OpenAPI-related discussions. However, with experience, we’ll be able to introduce optimization, speed up authoring, and ensure consistency from the start.