A controller stub is generated server-side scaffolding for operations described in an OpenAPI definition. It includes request and response models, routing, and controller logic to complete. Generating it from the definition reduces the risk that implementation work drifts from the published API reference; it does not replace checks against the running API. section 6.0 section 6.1
Use the OpenAPI definition as the starting point for changes:
- Update the definition when an operation’s request or response requirements change. section 6.1
- Regenerate the server stub for the chosen language and framework, then implement the operation in the generated controller. section 6.1 section 6.2.1
- Keep the client SDK and API reference aligned with the same definition, and test whether the running server actually conforms. section 6.0
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
The generation command supplies an OpenAPI file to OpenAPI Generator, selects Spring Boot, and sets the output directory and Java package locations. The generated project includes model and controller files; generation provides a starting point, not the operation’s finished behavior. section 6.2.1
Complete a generated operation
In the Spring Boot example, a developer adds viewProduct to the product controller. The method accepts a UUID path parameter, populates a Product, and returns an HTTP 200 response. A separate exception handler shapes an invalid-UUID request into a 400 error response. These behaviors require implementation beyond generating the stub. section 6.2.1
Do not confuse a controller stub with a stub API. A controller stub is code to build out on the server; a stub API is a limited simulation that returns predefined or uniform responses while consumers develop an integration. section 6.0 section 9.2
