An API reference says a response always contains `keywords`, but the live service omits it. The documentation and implementation have drifted. A source of truth (SOT) gives the team one authoritative place to record intended behavior: in a design-first workflow, the OpenAPI definition. Changing code without updating that definition—or coding from it by hand and missing a field—breaks the agreement. section 6.1
Use the definition as the starting point for each change:
- Update the OpenAPI definition when requirements change. Treat it as the *to-be* view: it may describe behavior not yet implemented. section 6.2.4 section 6.2.7
- Generate the server stub, models, routing, client SDKs, and reference documentation needed by the participating teams from the agreed definition. section 6.2 section 6.2.7
- Implement behavior the generated code does not supply, then check the running response. Keep an *as-is* definition that accurately describes what is implemented now. section 6.2.4 section 6.2.7
Adding required product-review fields
New requirements add integer `reviewRating` and `numberOfReviews` fields to a product response. First add them to `product-catalog-v1-1.oas.yaml`; then regenerate the response model. The regenerated `Product.java` gains getters and setters, but the custom controller must still populate the fields. Exclude that controller with `.openapi-generator-ignore` so regeneration does not overwrite its edits. Update the API reference from the definition and inspect the live response for both fields. section 6.2.4
Listing 6.5 Regenerating the Spring Boot service
openapi-generator-cli generate --input-spec product-catalog-v1-1.oas.yaml #1 --generator-name spring --ignore-file-override #2 product-catalog-service/.openapi-generator-ignore --additional-properties= library=spring-boot, apiPackage=com.acmepetsupplies.controller, modelPackage=com.acmepetsupplies.model, configPackage=com.acmepetsupplies.configuration, basePackage=com.acmepetsupplies, useTags=true
The regeneration command selects the revised OpenAPI file, the Spring generator, and an ignore file that protects custom controller code. section 6.2.4
Generation makes repeated design changes quicker and lets server, client, and documentation teams work from the same agreed definition; it does not by itself prove that the published reference matches every live response. Check behavior from components outside the service, such as an API gateway. Generating the definition from service code is another conformance approach, but it reverses which artifact leads. section 6.2.7 section 6.4
