Overview

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.
figure
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.
figure
Changes to the API design during the development phase may lead to a drift between the deployed API behavior and the original API design.
figure
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.
figure
Your next step is to deploy your API service to the API gateway.
figure
Publish your OpenAPI definition as an API reference on your developer portal.
figure
An API client SDK is a library that wraps an HTTP client that makes calls to an API.
figure
Using the OpenAPI definition as the SOT for generating artifacts
figure
Generating OpenAPI definitions from a Spring Boot application
figure

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.

FAQ

```html
What is the API conformance problem described in this chapter?The API conformance problem is the mismatch that can occur between your OpenAPI definition, your live API behavior, your generated client SDKs, and your published API reference documentation. The chapter shows how to reduce drift by generating artifacts from a single source of truth or by generating OpenAPI from code.
Why is it a problem when API reference documentation does not match the live API?When documentation and behavior differ, API consumers can be confused, file defect tickets, and lose trust in the API. This increases support costs and can slow adoption of the API.
What are the two main approaches to keeping APIs consistent with OpenAPI?The two main approaches are generated consistency and API conformance testing. Generated consistency means generating server stubs, client SDKs, and documentation from the OpenAPI definition, while conformance testing checks whether the running API matches the definition.
What does “source of truth” mean in this chapter?The source of truth is the authoritative artifact that defines what the API should do. In the generation approach, the OpenAPI definition is treated as the source of truth, and code, SDKs, and docs are generated from it.
How does generating server code from OpenAPI help with conformance?Generating server stub code from OpenAPI reduces manual translation errors and helps ensure the controller, request models, response models, and routing logic match the contract defined in the API specification.
What is a stub controller in OpenAPI-generated server code?A stub controller is generated server code that includes routing, method signatures, and often default or placeholder implementations. It represents the API operations and can be customized with business logic while keeping the contract aligned with the OpenAPI definition.
Why is the .openapi-generator-ignore file important when regenerating code?The .openapi-generator-ignore file prevents OpenAPI Generator from overwriting files you have customized manually, such as a controller implementation. This lets you regenerate updated model classes while preserving your custom code.
How does the chapter use OpenAPI Generator to create a Java Spring Boot service?The chapter uses openapi-generator-cli with the spring generator and spring-boot library to produce a Spring Boot project, including controller interfaces, models, configuration files, and supporting project metadata from the OpenAPI specification.
Why might an API gateway affect API conformance?An API gateway can return its own responses, such as authentication failures, rate-limit errors, or transformed requests and responses. Because these behaviors affect what consumers actually see, they must be reflected in the API definition or handled through gateway configuration and testing.
What are the benefits of generating client SDKs from OpenAPI?Generating client SDKs helps API consumers interact with the API through a language-specific library instead of writing raw HTTP calls. It also ensures the client methods, models, and request behavior stay aligned with the API contract and can be regenerated when the specification changes.
```

pro $24.99 per month

  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose one free eBook per month to keep
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime

lite $19.99 per month

  • access to all Manning books, including MEAPs!

team

5, 10 or 20 seats+ for your team - learn more


Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Automating API Delivery Automating API Delivery ebook for free
Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Automating API Delivery Automating API Delivery ebook for free
Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Automating API Delivery Automating API Delivery ebook for free