6 API conformance: Generating code and API definitions
When a public API’s live behavior drifts from its OpenAPI definition, consumers see mismatches in documentation, generated clients, and actual responses, which creates confusion and support overhead. The chapter frames this as an API conformance problem and argues that the safest way to reduce human error is to treat the OpenAPI definition as the source of truth, then generate server stubs, SDKs, and reference documentation from it. It also notes that conformance can be enforced through runtime testing, but this chapter emphasizes generated consistency as the primary approach.
The main example shows how OpenAPI Generator can create a Spring Boot service scaffold from an API spec, including controller interfaces, routing annotations, request and response models, and example payloads. After generating the service, the developer customizes the controller implementation, adds centralized error handling that returns responses matching the documented error schema, and runs the app to confirm that both successful and invalid requests behave according to the contract. The chapter then extends this workflow to deployment behind an API gateway, showing that gateway configuration for routing and authentication must also align with the externally visible API behavior.
The same source-of-truth pattern is then applied to publishing and maintaining documentation and SDKs. When the API contract changes, the generated models and reference docs are regenerated so the service implementation and portal stay in sync, while ignore files preserve custom controller code during regeneration. The chapter also demonstrates generating a Java client library from the updated definition and using it in a test to call the API through the gateway. Finally, it explains the reverse workflow—generating OpenAPI from code with tools like springdoc-openapi—while warning that gateway transformations, missing examples, and incomplete annotations can still cause documentation to diverge from what clients actually experience.
At the build stage, you can generate server stub code and client SDKs from your API definition. You transform your OpenAPI definitions into API reference documentation and publish it to your developer portal.
The response from the public API is missing a field marked as mandatory in the API reference. There is a drift between the API reference and the live API.
Changes to the API design during the development phase may lead to a drift between the deployed API behavior and the original API design.
Update the OpenAPI definition every time the API requirements change, and then generate the API service controller stub from the OpenAPI definition. This ensures the implementation and published API reference conform.
Your next step is to deploy your API service to the API gateway.
Publish your OpenAPI definition as an API reference on your developer portal.
An API client SDK is a library that wraps an HTTP client that makes calls to an API.
Using the OpenAPI definition as the SOT for generating artifacts
Generating OpenAPI definitions from a Spring Boot application
Summary
- API conformance is about ensuring that the published API reference documentation is consistent with the API server behavior and the API client SDK.
- One way to help ensure API conformance is by generating artifacts such as API service code, API client SDKs, and API reference documentation from the OpenAPI definition. In this approach, the API definition is the SOT on the expected or to-be behavior.
- Generating artifacts from OpenAPI has the advantage of being quick (compared to writing schema tests) and allows teams to work in parallel from an agreed API definition SOT.
- Generating an API definition from API service code (and then using the definition to create reference documentation and client SDKs) is another approach for ensuring that the API behavior matches the API reference.
- The published API reference has to take into account API responses that come from components outside the API service, such as the API gateway.
- OpenAPI generator is a popular library for generating server code, client SDKs, and reference documentation from OpenAPI definitions. It has various options for customizing the generated code.
Automating API Delivery ebook for free