17 Optimizing an OpenAPI document
Designing OpenAPI documents without care often leads to duplication and inconsistencies that slow authorship and maintenance. This chapter explains how to optimize an OpenAPI description by fully leveraging OpenAPI and JSON Schema to make designs more consistent, reusable, and easier to evolve. Optimization is treated as a distinct step after the initial interface design so that HTTP and data-modeling choices remain clear; with experience, many of these practices can be introduced earlier without derailing design discussions.
The chapter walks through concrete techniques to eliminate repetition and tighten consistency. For data models, it recommends reusable schemas under components.schemas, deep references to inner properties to avoid a proliferation of micro-schemas, and overriding descriptions next to $ref for contextual clarity. It shows how a single read‑write model can serve requests and responses using readOnly/writeOnly, and how allOf can compose a complete schema from a summary plus additional properties. For requests, define shared parameters at the path level, create reusable parameters under components.parameters, and even group query parameters via an object parameter that serializes into multiple keys (e.g., pagination). Similarly, reuse request bodies (components.requestBodies), response headers (components.headers), and responses (components.responses), overriding descriptions as needed; be mindful of limitations such as response status codes and header names being keys at the use site. The chapter also cautions against over-optimization when it makes documents harder to read.
To extend consistency across APIs, the chapter advocates building OpenAPI libraries that house shared schemas, parameters, headers, and responses, referenced via file-path plus JSON Pointer. These library files should be independently valid (full OpenAPI or standalone JSON Schema), so they can be edited and validated on their own; avoid partial snippets, watch for breaking changes that would ripple across APIs, and use tooling that can bundle split files when needed. Finally, it suggests enriching API design guidelines with OpenAPI authoring rules—where libraries live, when to use deep references versus reusable micro-schemas, and how to apply these patterns consistently—ideally reinforced by automated checks. The result is a maintainable, consistent, and scalable OpenAPI corpus that supports better API governance.
We’re back to the "Describe the programming interface" stage of the design process. We must optimize our OpenAPI document to ensure consistency and simplify its evolutions. To avoid mixing design and OpenAPI concerns, we should optimize the OpenAPI document after the "Design the programming interface" step.
FAQ
What is OpenAPI document optimization and when should I do it?
It’s the practice of using OpenAPI and JSON Schema features to reduce duplication and ensure consistency across schemas, parameters, request/response bodies, and headers. Do it after your initial HTTP and data design so you don’t mix design decisions with format-specific concerns. With experience, you can blend some optimizations earlier without derailing design.How do reusable schemas and deep references help avoid duplication?
- Define models once undercomponents.schemas and reuse them via $ref (for example, #/components/schemas/Product).- Use deep references to target inner parts of a schema (for example, reuse
Product’s id via #/components/schemas/Product/properties/id) instead of creating many micro-schemas.When should I create sub-schemas versus using deep references?
- Create sub-schemas when a piece of data stands well on its own across multiple models (for example,SupplierSummary).- Use deep references when a fragment naturally belongs inside a parent resource (for example, a product’s
id or supplier object) to avoid bloating components.schemas with tiny types.Can I override descriptions when using $ref? What about OpenAPI 3.0?
In OpenAPI 3.1 you can place summary/description next to a $ref to override the referenced component’s text. In OpenAPI 3.0 this is not supported (tools ignore or error). A workaround using allOf exists but makes docs harder to read; prefer upgrading to 3.1.How can I use readOnly and writeOnly to create a single read-and-write model?
Mark server-generated fields (for example, id) as readOnly: true and input-only fields as writeOnly: true. Then reuse the same schema in requests and responses. Caveat: heavy use of writeOnly often signals structural differences between input and output—keep those differences minimal so clients can round-trip data easily.How do I build a complete schema from its summary using allOf?
Keep the summary schema as-is, then define the full schema as an allOf array with two items: a $ref to the summary plus an inline schema with the remaining properties/requirements. This avoids copy-paste drift and works alongside readOnly/writeOnly flags.What’s the best way to keep parameters consistent across operations?
- Put shared parameters at the path level (not onlyin: path; headers or other types can go there if all operations share them).- Define reusable parameters under
components.parameters and reference them where needed.- For groups of query parameters (for example, pagination), define one reusable object parameter whose properties become multiple query params via default serialization (for example,
next, limit). Add a clear description so tools and readers understand usage.How can I reuse request bodies, response headers, and responses?
- Request bodies: define undercomponents.requestBodies, reference via $ref, and optionally override description where used.- Response headers: define under
components.headers and reference them under a concrete header name. Note: the reusable header’s name isn’t defined in components—it’s the key under headers where you use it.- Responses: define under
components.responses and reference them under a specific HTTP status code. The status code itself can’t be part of the reusable component.How do I share components across APIs using libraries, and how do references work?
Create an OpenAPI “library” file withinfo and components (no paths/webhooks). Reference components with $ref that combines the file path/URL and a JSON Pointer (for example, /path/shared-components.yaml#/components/parameters/Pagination). Most component types can be shared this way; securitySchemes are referenced by name, not $ref, and are a known limitation.What pitfalls should I watch for when optimizing and splitting files?
- Don’t over-optimize: heavy use ofallOf and deep nesting can hurt readability; a little duplication can be acceptable.- Avoid breaking changes in shared libraries—they impact all consuming APIs.
- Ensure each library file is a valid, standalone OpenAPI or JSON Schema document (avoid partial YAML snippets).
- Some tools don’t handle multi-file specs; use a bundler (for example, Redocly CLI) to produce a single file for downstream tooling.
The Design of Web APIs, Second Edition ebook for free
