openapi-contract-first

OpenAPI contract-first

Workflow

1. Edit src/main/resources/openapi/openapi.yaml (or whatever the project's path is — detect via detect-stack.sh).
2. Run the OpenAPI diff against the previous version (committed in _baseline.json).
3. If breaking, either:
   • Pick a non-breaking alternative (additive field, new endpoint, version the path), OR
   • File an ADR (adr/NNN-breaking-api-change.md) and proceed.
4. Generate DTOs (records) via openapi-generator Maven plugin.
5. Write the controller; the slice test (@WebMvcTest) consumes the generated request/response records.

Breaking vs non-breaking

Non-breaking (no ADR required):

• Adding a new endpoint.
• Adding an optional request field.
• Adding a response field (clients should ignore unknown).
• Loosening a constraint (min: 1 → min: 0).
• Adding a new enum value, only if the consumer contract documents that they tolerate unknowns.

Breaking (ADR required):

• Removing or renaming any field.
• Changing a type (integer → string).
• Tightening a constraint.
• Changing a path or HTTP method.
• Changing an HTTP status for an existing condition.
• Adding a required request field.
• Removing an enum value.

Springdoc check

If springdoc is on the classpath, also run a runtime vs static check: start the app, fetch /v3/api-docs, diff against openapi.yaml. They must match. The skill's hook for this is openapi-runtime-vs-static.

Generation hint

Configure openapi-generator to:

• generatorName: spring
• library: spring-boot
• useSpringBoot3: true (works for Boot 4 too at the time of writing)
• interfaceOnly: true (we write the controller; generator only produces interface + DTOs)
• useTags: true
• dateLibrary: java8 (i.e. java.time)
• useJakartaEe: true
• DTOs as records: serializationLibrary: jackson, additionalModelTypeAnnotations: "", and prefer Java records via the useRecord flag where supported.

Worked example

Adding POST /checkout/{orderId}/gift-card: