19 Enriching API design artifacts

This chapter explains how to enrich an API design reference kit so it better serves design discussions and the next stages of the API lifecycle. The kit—built around an API capabilities canvas, an OpenAPI document, and design guidelines with a shared library and lint rules—acts as a living, central source of truth. It helps teams refine needs, model concepts and operations, align on security and behavior, and then carry that clarity into development, testing, deployment, and consumption; for private APIs, it is often the primary resource developers rely on. The emphasis is on practical, context-aware enhancements that improve understanding and accuracy without turning the kit into full-blown public documentation.

Several low-effort improvements raise the kit’s usefulness: adding a concise overview and cross-references in OpenAPI, grouping operations by concepts and use cases with tags, and—where needed—lightweight use case descriptions. Data models gain precision by leveraging JSON Schema keywords for ranges, sizes, patterns, enumerations, and defaults, reducing ambiguity for documentation, code generation, testing, and mocking. Carefully crafted examples further clarify intent: small, property-level samples in schemas and richer, documented examples for parameters, bodies, and headers in OpenAPI, with reuse to avoid duplication and consistent naming to connect request/response pairs. The chapter stresses balancing effort and value—favoring focused examples and shared patterns, supported by lint rules and compatible tooling—over exhaustive, portal-grade artifacts during design.

To smooth implementation, the chapter advocates embedding targeted implementation notes in OpenAPI or guidelines and adapting the spec for code generation by using stable tags, operation identifiers, and JSON Schema features supported by generators. For experiential feedback, teams can spin up basic mocks directly from OpenAPI or prefer an early implementation prototype when realistic behavior is needed, keeping heavy scripted mocks for later. Finally, adding functional tests during design can clarify complex logic, reduce cross-team friction, and support standard APIs, while remaining mindful that broader performance and security testing unfold later. Overall, the recommended enrichments are modular, tool-friendly, and tailored to context, turning a solid kit into a durable accelerator for building, testing, deploying, and documenting APIs.

Though "Enrich API design artifacts" is the final step in the sequential design process diagram, we work on the API design reference kit across all steps. Its content is helpful during design and the subsequent API lifecycle stages.

The API design reference kit contains all the artifacts necessary to describe an API and help understand it fully. Artifacts can be documents (such as a wiki page or guidelines), machine-readable documents (such as OpenAPI), applications (such as a simulated API or linter), or pieces of code (such as tests).

Add an info.summary is necessary for understanding. Leverage Markdown in info.description or the root externalDocs.url to link the OpenAPI document to other artifacts.

Group operations by adding tags. Sort groups by adding the root-level tags list. Operations can’t be reordered in groups.

By leveraging a tag’s externalDocs, we may add a link to the sheet and line corresponding to the use case in the API capabilities canvas.

The root tag object supports a Markdown description; we may use it to describe the order of the operations, but that may be a lot of work.

JSON Schema allows for defining numerical ranges and array and string lengths. These ranges can be open-ended.

JSON Schema can describe a value with pattern (regex), enum (authorized values), and default (default value).

To describe data better, add a single example or examples list to any part of a schema; this will improve schema documentation and generated samples.

Add an examples map near the schema of a parameter, request or response body, or response header to illustrate it better with one or multiple documented examples.

Define examples under components.examples and use them with a $ref to avoid duplication.

Use the same example key (for tools) and summary (for documentation readers) to enable connecting examples.

FAQ