openapi-contract-first

Contract-first OpenAPI workflow — author or update the spec, run the diff gate, regenerate types, write the controller. Use when adding or changing an HTTP endpoint.

SKILL.md

GitHub

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:

paths:
  /checkout/{orderId}/gift-card:
    post:
      operationId: applyGiftCard
      tags: [Checkout]
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ApplyGiftCardRequest' }
      responses:
        '200':
          description: Applied
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApplyGiftCardResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
components:
  schemas:
    ApplyGiftCardRequest:
      type: object
      required: [code, orderTotalCents]
      properties:
        code: { type: string, minLength: 1 }
        orderTotalCents: { type: integer, format: int32, minimum: 0 }

Anti-patterns

  • Hand-writing DTOs that drift from the spec.
  • Using application/x-www-form-urlencoded for new APIs.
  • additionalProperties: true on response schemas (loses type safety on the client).
  • Returning 200 for errors with a status field in the body.
  • One giant OpenAPI.yaml with no tags or grouping.