When an API definition and its implementation are maintained separately, they can drift apart. Code generation reduces that risk by treating the OpenAPI definition as the source of truth (SOT): define the API first, then generate service scaffolding from it. The generated controller, routing, request, and response code provides a starting point for implementation, not a replacement for it. section 6.2
For a Java Spring Boot service, OpenAPI Generator can create a project from an OpenAPI file. Its CLI command identifies the input specification, selects the Spring generator, names the output directory, and sets packages for controllers, models, and configuration. The CLI is a Node application that downloads and runs the generator's Java executable. section 6.2.1
Listing 6.1 Generating a Spring Boot application from OpenAPI
openapi-generator-cli generate --input-spec product-catalog-v1-0.oas.yaml #1 --generator-name spring #2 --output product-catalog-service --additional-properties= #3 library=spring-boot, #4 apiPackage=com.acmepetsupplies.controller, #5 modelPackage=com.acmepetsupplies.model, #6 configPackage=com.acmepetsupplies.configuration, #7 basePackage=com.acmepetsupplies, #8 useTags=true #9
Use this command as the generation template: change the input file, output directory, and package names for your service. Keep the comma-separated additional properties together without spaces between them. section 6.2.1
Inspect the output before adding behavior. The project includes build and configuration files, generated model classes, and API controller files. Its README identifies the generated project, while openapitools.json records the generator package version used. Generated API interfaces carry operation and response annotations; the application still needs implementation of the requested behavior. section 6.2.1
Implement and check a product lookup
A viewProduct controller method can accept a UUID path parameter, populate a generated Product model, and return it with HTTP 200. A request made with curl can then display the product JSON. A non-UUID identifier instead produces an HTTP 400 error response in the completed example. These checks distinguish a generated route and model from a working endpoint with error handling. section 6.2.1
When requirements change, update the SOT first and regenerate the affected artifacts, which may include server code, client SDKs, and reference documentation. Teams can work on those artifacts in parallel once they agree on the definition. Keep a forward-looking “to-be” definition distinct from the “as-is” definition that describes what the service currently implements; a design change is not implemented merely because it appears in the specification. section 6.2.7
