Md Sanwar Hossain

Senior Software Engineer · Java, Spring Boot, Kubernetes

Contract-First API Development with OpenAPI 3.1: Code Generation, Schema Validation & Breaking Change CI

Contract-first API development is a discipline that treats the OpenAPI specification as the single source of truth, written before implementation begins, enforced throughout the development lifecycle, and used to generate both server stubs and consumer SDKs. This post walks through the complete workflow, toolchain, and operational trade-offs for teams ready to move beyond code-first annotation-based API documentation.

1. Introduction

A platform engineering team at a mid-size fintech company maintains over 30 microservices, each exposing REST APIs consumed by multiple internal teams and a growing base of external partners. Every sprint, the team lead fields the same complaints: a mobile team updates their app only to discover that the /payments/initiate endpoint now returns a required field named transactionReference instead of txnRef. A partner integration breaks silently because an enum value was added to PaymentStatus without notice. A consumer team discovers in a staging incident that the request schema for /accounts/transfer added a new required field idempotencyKey — something that should have blocked the PR in CI but instead only surfaced during integration testing two sprints later.

The pattern is consistent and costly: API changes ship without consumers being informed, without formal versioning decisions, and without automated gates to catch regressions. Post-mortems always reach the same conclusion — the team writes implementation first and documents APIs as an afterthought, generating OpenAPI specs from Swagger annotations that frequently lag reality. The spec exists, but nobody trusts it. Consumer teams test empirically — they make a call, see what comes back, and document the undocumented behaviors they discover. Now they are coupled to implementation details that were never intended as a public contract, and when those implementation details change, their integrations break silently.

Contract-first API development inverts this flow entirely: the OpenAPI specification is written before implementation, treated as the authoritative contract, and enforced throughout the development lifecycle — from code generation to runtime validation to CI breaking-change gates. The spec is a design artifact, reviewed in pull requests by API designers, consumer team representatives, and architects before a single line of implementation code is written. When the spec is approved, code generation produces server-side interfaces and consumer SDKs simultaneously, ensuring both sides of the API boundary are working from the same contract.

This post walks through the complete workflow and toolchain for contract-first development: what makes OpenAPI 3.1 meaningfully more capable than its predecessor, how to configure the five-phase workflow from spec authoring through runtime validation, what the common failure modes and trade-offs look like in practice, and when the discipline adds more overhead than value. By the end, you will have a clear picture of how to implement contract-first development in a Spring Boot microservices environment and how to integrate it into a GitHub Actions CI pipeline with automated breaking-change detection.

2. The Code-First Anti-Pattern and Why It Fails

The code-first approach — annotate your Java controllers with Swagger/Springdoc annotations, run a spec generator at build time — is seductive because it feels like documentation is "for free." In practice, the documentation is never quite accurate. Annotations must be manually synchronized with business logic changes. A developer renames a field, forgets to update the annotation, and the published spec is now wrong. Generated specs often reflect the Java type system rather than the intended API contract: Optional fields appear as nullable but required in practice, polymorphic types are poorly represented, and enum values that exist in the type but are no longer valid in the domain are still advertised. This gap between spec and reality means consumer teams cannot trust the spec as a reliable contract.

The trust deficit has downstream consequences. Consumer teams test empirically — make a call, see what comes back — and document the undocumented behaviors they discover. Now they are coupled to implementation details that were never intended as a public contract, and when those details change, their integrations break silently. The spec becomes a lagging indicator of reality rather than a specification of intent. Teams invest engineering time in defensive coding patterns — null checks for fields that should always be present, fallback logic for enum values that are no longer returned — that accumulate as technical debt across every consumer.

Breaking changes ship without CI gates because there is no canonical contract to diff against. A developer adds a required field to a request body. The Swagger annotation is updated. The generated spec changes. But no CI step compares the new spec against the previous published spec and fails the PR if backward compatibility is broken. The breaking change reaches production because no automated system was watching for it. The consequences compound: partner integrations require emergency hotfixes, internal consumers add defensive null-checks that persist for years, and consumer trust in the platform team's APIs erodes sprint by sprint.

3. OpenAPI 3.1, Contract-First Principles, and Toolchain Overview

OpenAPI 3.1 (released in February 2021) aligns with JSON Schema draft 2020-12, resolving a long-standing frustration in 3.0 where OpenAPI used a subset of JSON Schema that diverged in subtle but impactful ways. In 3.1, the schema object IS a JSON Schema object, which means you can use $vocabulary, unevaluatedProperties, prefixItems, and the full range of JSON Schema validation keywords. OpenAPI 3.1 also adds a first-class webhooks object for documenting async push events, improves discriminator handling for polymorphic schemas, and allows requestBody to be used in GET and HEAD operations. These improvements make 3.1 substantially more expressive for complex domain models with inheritance, strict schema validation requirements, and mixed sync/async interaction patterns.

For contract-first development, the spec is the source of truth, written before any implementation exists. Operationally this means: the API designer or tech lead writes the OpenAPI YAML for a new endpoint; the spec is reviewed and approved via PR; openapi-generator generates server stubs (interface plus model classes) for the implementing team and client SDKs for consumer teams; the implementing team fills in the business logic inside the generated interface implementations; at no point does anyone write a Swagger annotation. The spec drives everything downstream, from the code structure to the mock server that consumer teams use during parallel development to the request validation middleware that enforces the spec at runtime.

The toolchain supporting this workflow includes four major components. Spectral provides spec linting — enforcing naming conventions, required fields, security schemes, and custom organizational rules encoded as JavaScript or YAML rulesets. openapi-generator handles code generation for server stubs and client SDKs across more than 50 target languages and frameworks, with highly configurable templates for Spring Boot, Quarkus, TypeScript, Go, and many others. oasdiff performs breaking change detection — it compares two spec versions and classifies each difference as breaking, non-breaking, or informational, with a rich taxonomy of change types that maps directly to the semantic versioning impact. Prism generates a fully functional mock server from the spec, including example responses and request validation, allowing consumer teams to develop and test against the API contract before the implementing team has finished the business logic.

The toolchain for contract-first development integrates cleanly with Java backends. Spring Boot projects generated from OpenAPI specs often use virtual threads (see our post on Java Structured Concurrency) for the parallel fan-out operations that many contract endpoints require — aggregating data from multiple upstream services per request. The combination of a formally specified API contract and structured concurrency for the implementation layer produces services that are both reliably documented and efficiently executed.

4. The Contract-First Workflow in Practice

The contract-first workflow has five phases. Phase 1 — Spec authoring: The API designer writes the OpenAPI 3.1 YAML. This is a design artifact, not a code artifact. It lives in a dedicated api-contracts repository (or a contracts/ directory in the service repo) and is subject to the same PR review process as code. Good spec authoring practices include: defining all schemas in the components/schemas section and referencing them via $ref (avoid inline schemas); using oneOf and discriminator for polymorphic types; documenting every error response explicitly; and adding x-internal or x-beta extensions to mark non-stable endpoints. The spec review should involve representatives from both the producing team and at least one consuming team.

Phase 2 — Spectral linting: Every PR that modifies the spec runs a Spectral lint check in CI. Custom Spectral rulesets enforce org-specific conventions: all paths must be kebab-case, all schemas must have a description, all success responses must include a requestId field, security schemes must be defined for non-internal endpoints. Spectral's severity levels allow teams to distinguish between blocking violations (error) and advisory feedback (warn, info, hint). Phase 3 — Code generation: After spec approval, openapi-generator generates server-side interface and model classes. The generated code is committed to the repo with a .gitattributes entry marking generated files as auto-generated to suppress diff noise in PRs. Consumer teams pull pre-built client SDKs from an internal package registry — Maven for Java, npm for TypeScript.

Phase 4 — Runtime validation: A request/response validation filter (using openapi4j or swagger-request-validator) validates every incoming request against the published spec and every outgoing response against the spec. Schema mismatches are logged and, in strict mode, rejected with a 400 for request validation failures or a 500 for response validation failures. Runtime validation serves as a safety net when implementation diverges from the spec — for example, when a developer customizes generated code and introduces a discrepancy, or when an upstream dependency returns data that violates the expected schema. The validation logs also serve as a drift detector over time.

Phase 5 — Breaking change detection: A CI job uses oasdiff to compare the PR's spec against the version on the main branch. If any breaking changes are detected, the PR is failed with a detailed report listing the specific changes and their severity. oasdiff's breaking change taxonomy covers field removals, type changes, enum value removals, required field additions to request bodies, security requirement changes, and dozens of other categories. Teams can configure oasdiff to fail only on breaking changes (ERR level) while passing non-breaking changes (INFO level), giving a nuanced signal rather than a binary pass/fail. This phase is the most impactful addition to the workflow — it is the automated gate that the code-first teams in the introduction were missing.

5. Architecture and Code Examples

The following examples illustrate the concrete artifacts produced and consumed at each phase of the contract-first workflow. Starting from an OpenAPI 3.1 YAML spec for a payments endpoint, the workflow produces generated server stubs, a CI configuration for breaking-change detection, and a runtime validation filter — all driven by the spec as the primary artifact.

The OpenAPI 3.1 spec below demonstrates key 3.1 features: oneOf with a discriminator for polymorphic payment methods, component-level schema definitions referenced via $ref, and a format: uuid constraint on the idempotency key. This level of precision in the spec ensures generated model classes include the correct validation annotations, and that oasdiff can detect breaking changes at the field level.

openapi: "3.1.0"
info:
  title: Payments API
  version: "2.0.0"
paths:
  /payments/initiate:
    post:
      operationId: initiatePayment
      summary: Initiate a new payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentRequest"
      responses:
        "202":
          description: Payment accepted for processing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
components:
  schemas:
    PaymentRequest:
      type: object
      required: [amount, currency, idempotencyKey, paymentMethod]
      properties:
        amount:
          type: integer
          description: Amount in minor units (e.g., cents)
          minimum: 1
        currency:
          type: string
          pattern: "^[A-Z]{3}$"
          description: ISO 4217 currency code
        idempotencyKey:
          type: string
          format: uuid
        paymentMethod:
          $ref: "#/components/schemas/PaymentMethod"
    PaymentMethod:
      oneOf:
        - $ref: "#/components/schemas/CardPayment"
        - $ref: "#/components/schemas/BankTransfer"
      discriminator:
        propertyName: type
        mapping:
          card: "#/components/schemas/CardPayment"
          bank: "#/components/schemas/BankTransfer"

# Generate Spring Boot server stub
openapi-generator-cli generate \
  -i api-contracts/payments-api.yaml \
  -g spring \
  -o services/payments-service/src/main/java \
  --additional-properties=useSpringBoot3=true,interfaceOnly=true,useTags=true \
  --package-name com.example.payments.api

# Generate TypeScript client SDK
openapi-generator-cli generate \
  -i api-contracts/payments-api.yaml \
  -g typescript-fetch \
  -o sdks/payments-ts-client \
  --additional-properties=supportsES6=true,npmName=@example/payments-client,npmVersion=2.0.0

name: API Contract Checks
on: [pull_request]
jobs:
  breaking-change-detection:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install oasdiff
        run: |
          curl -fsSL https://raw.githubusercontent.com/tufin/oasdiff/main/install.sh | sh
      - name: Check for breaking changes
        run: |
          oasdiff breaking \
            origin/main:api-contracts/payments-api.yaml \
            api-contracts/payments-api.yaml \
            --format text \
            --fail-on ERR
      - name: Spectral lint
        uses: stoplightio/spectral-action@v0.8.11
        with:
          file_glob: 'api-contracts/*.yaml'
          spectral_ruleset: '.spectral.yaml'

@Component
public class OpenApiValidationFilter implements Filter {
    private final OpenApiInteractionValidator validator;

    public OpenApiValidationFilter() {
        this.validator = OpenApiInteractionValidator
            .createForSpecificationUrl("classpath:api-contracts/payments-api.yaml")
            .withLevelResolver(LevelResolverFactory.withDefaultLevels())
            .build();
    }

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest httpReq = (HttpServletRequest) req;
        HttpServletResponse httpRes = (HttpServletResponse) res;

        // Wrap to allow multiple reads of request/response bodies
        CachingRequestWrapper cachedReq = new CachingRequestWrapper(httpReq);
        CachingResponseWrapper cachedRes = new CachingResponseWrapper(httpRes);

        chain.doFilter(cachedReq, cachedRes);

        SimpleRequest request = buildSimpleRequest(cachedReq);
        SimpleResponse response = buildSimpleResponse(cachedRes);

        ValidationReport report = validator.validate(request, response);
        if (report.hasErrors()) {
            log.warn("Schema validation errors for {} {}: {}",
                httpReq.getMethod(), httpReq.getRequestURI(),
                report.getMessages());
        }
        cachedRes.copyBodyToResponse();
    }
}

For the generated service layer that orchestrates multiple downstream calls, pair the generated stubs with StructuredTaskScope.ShutdownOnFailure to ensure all parallel upstream calls are properly cancelled if any single call fails — a common pattern in API aggregation services.

6. Failure Scenarios and Trade-offs

Generated code churn is the most immediately visible friction point in a contract-first workflow. Every time the spec changes, regenerating code produces a large diff in version control — often hundreds of modified files for model classes and API interfaces, even for a small spec change. This makes PRs difficult to review because the substantive logic changes are buried in generated noise. The mitigation is twofold: add a .gitattributes entry marking generated files with linguist-generated=true (which suppresses the diff in the GitHub UI) and -diff (which excludes them from git diff by default); and separate the generated code into its own module so that spec changes don't pollute the diffs for service logic changes. Reviewers can then focus their attention on the spec change and the business logic change in separate PRs.

Over-specified schemas causing false-positive breaking changes create alarm fatigue that undermines the value of the oasdiff gate. If your spec uses additionalProperties: false everywhere — which is a good security practice to prevent undocumented fields — oasdiff will flag as breaking any change that adds a new optional field to a response schema, because the strict schema previously rejected it. This is technically correct from a spec perspective but creates operational friction when consumers are actually tolerant of new fields. The mitigation is to distinguish between strict inbound validation (apply additionalProperties: false on request schemas, where unknown fields in consumer requests should be rejected) and lenient outbound documentation (allow additional properties on response schemas to support additive evolution, consistent with the robustness principle).

Spectral rule fatigue is a pattern where large rulesets with hundreds of rules produce lint reports that developers stop reading. When every PR produces 40 warnings, developers begin ignoring the warning output entirely — including the critical ones. The mitigation is to start with five to ten critical rules, measure rule violation rates over several sprints, and add rules incrementally. Use Spectral's severity levels to separate blocking violations (error) from advisory ones (warn, info, hint). Reserve error severity for rules that catch genuine reliability or security issues, and use warn for style and convention violations that should be fixed but don't block merging.

Generator template drift occurs when you upgrade openapi-generator-cli versions and the generated code templates change. This can produce large diffs that are entirely cosmetic — formatting changes, import ordering, annotation syntax — but must be committed to keep the generated code in sync with the generator version. These cosmetic diffs pollute blame history and can mask real changes if reviewed carelessly. The mitigation is to pin the openapi-generator-cli version in your CI configuration and plan explicit upgrade windows, reviewing the generated code diff as a dedicated commit before committing any business logic changes on top of it. Treat generator upgrades as a controlled maintenance activity, not an incidental change bundled with a feature.

7. When NOT to Use Contract-First Development

Internal tooling with a single consumer: If a microservice is consumed only by one other service owned by the same team, the formality of a separate contract spec, Spectral linting, and breaking-change CI adds overhead that outweighs the benefit. A shared interface in a common library, versioned together, is simpler and equally safe. Contract-first development pays off when consumers are decoupled from the producer — different teams, different release cycles, or external partners. The discipline is fundamentally about managing the cost of coordination across organizational or deployment boundaries. When those boundaries don't exist, the coordination cost is low enough that the toolchain overhead is not justified.

Rapidly prototyping new APIs: During early exploration, the API shape changes multiple times per day as the team discovers what the domain actually requires. Writing and maintaining a spec during this phase creates friction without corresponding safety — there are no consumers to break yet, and the cost of spec maintenance is high relative to the value. A practical approach is to prototype code-first with informal Swagger annotations during the exploration phase, then formalize the contract when the API stabilizes and is ready for consumption. The contract-first discipline applies at the stabilization point, not during initial exploration, where it would slow down the discovery process without delivering safety benefits.

GraphQL-based APIs: GraphQL's SDL (Schema Definition Language) serves a similar purpose to OpenAPI for query-based APIs — it is an explicit, machine-readable contract that describes available types, queries, mutations, and subscriptions. Tooling like graphql-inspector provides breaking-change detection, code generation, and schema linting for GraphQL. Applying OpenAPI contract-first to a GraphQL API adds no value and creates confusion about which schema is authoritative. If your API is GraphQL, invest in GraphQL-native schema governance tooling rather than OpenAPI tooling — the domain model is different enough that the two should not be conflated.

Extremely simple CRUD APIs: A microservice that is a thin CRUD layer over a single database entity, consumed by one frontend that the same team owns, doesn't justify the contract-first toolchain. The complexity of setting up OpenAPI generator, Spectral, oasdiff, and runtime validation middleware is significant — probably two to three sprints of investment. Apply it where APIs have multiple consumers, complex schemas, external contractual obligations, or where the cost of a breaking change in production is high enough to justify the investment.

8. Optimization Techniques

Spectral custom rulesets for org-specific conventions are one of the highest-leverage optimizations available to teams adopting contract-first development. Beyond the standard OpenAPI validation rules, Spectral allows you to write rules that encode your team's conventions precisely. Useful examples include: all operation IDs must be camelCase; all 2xx responses must include a correlationId header; all paths must have at least one security scheme defined (unless tagged x-public); pagination parameters must follow a standard naming convention (page, pageSize, cursor). These rules make API reviews faster by automating the checklist that previously lived only in the reviewer's head, and they make the conventions explicit and discoverable for new team members joining the platform team.

Incremental code generation reduces the CI cost of the generation phase in large codebases where full regeneration on every spec change is slow. Use openapi-generator's --global-property option to generate only changed operations, or maintain a Makefile target that compares spec checksums and only regenerates when the spec has actually changed. For monorepos containing many services with separate specs, a git diff check against each spec file before running generation can prevent unnecessary regeneration in services whose specs were not modified in the PR — a significant CI time saving when running in a large monorepo.

Contract testing with Pact alongside OpenAPI provides complementary coverage that addresses a gap in pure spec-based validation. OpenAPI defines the shape of the API; Pact verifies that the provider actually behaves according to interactions that specific consumers have expressed. These are complementary: OpenAPI catches structural breaking changes (field renamed, type changed, required field added), while Pact catches behavioral breaking changes (field present but semantically wrong, error response body changed, status code semantics shifted). Running both in CI provides defense in depth against API compatibility regressions — OpenAPI validation operates at the structural layer, Pact operates at the behavioral layer, and together they cover significantly more of the compatibility surface than either tool alone.

API versioning strategy encoded in the spec is the right place to document and enforce your versioning approach. URI versioning (/v1/payments) makes the version explicit in every URL — easy to route, easy to deprecate, and immediately visible in logs. Header versioning (Accept: application/vnd.example.v2+json) keeps URLs clean but adds routing complexity and is less visible in logs. Whatever strategy you choose, encode it consistently in the spec: use servers[].url for URI versioning, or document the version header in the components/headers section for header versioning. Deprecate old versions with the deprecated: true flag on operations, giving consumers a documented sunset timeline backed by the spec rather than an ad-hoc email announcement.

9. Key Takeaways

• Contract-first development treats the OpenAPI spec as the source of truth: it is written before implementation, reviewed as a design artifact, and enforced via CI — never auto-generated from code annotations.
• OpenAPI 3.1's full JSON Schema draft 2020-12 alignment enables richer schema validation, including unevaluatedProperties and $vocabulary, making it more expressive than the 3.0 subset.
• oasdiff in CI is the most impactful single addition to an API development workflow: it automatically classifies spec changes as breaking or non-breaking and fails PRs that introduce backward incompatibilities.
• Runtime request/response validation (openapi4j, swagger-request-validator) catches schema drift between spec and implementation, providing a safety net when generated code is customized or implementation diverges from the spec.
• Spectral custom rulesets encode organizational API conventions into automated checks, replacing checklist-based code review for style and consistency issues.
• Contract testing with Pact complements OpenAPI structural validation by verifying behavioral compatibility from the consumer's perspective — the two tools cover different dimensions of API compatibility.

10. Conclusion

The code-first approach to API development is a debt-generating pattern that compounds with every new consumer. As consumer count grows, the cost of an unannounced breaking change scales linearly — one change, N broken consumers, N incident response threads, N post-mortems with the same root cause. Contract-first development with OpenAPI 3.1 inverts this by making the spec the single source of truth and automating the enforcement of compatibility guarantees throughout the development lifecycle. The toolchain is mature, open source, and widely supported: Spectral for lint, openapi-generator for code generation, oasdiff for breaking-change CI, and Prism for mock servers. Each tool addresses a specific failure mode that the code-first workflow leaves unguarded.

The initial investment in workflow setup — establishing the spec-first discipline, configuring CI gates, setting up the code generation pipeline, training the team on what constitutes a breaking change — pays for itself in the first sprint where a breaking change is caught before it reaches production. The avoided incident is invisible, which is the nature of preventive engineering. But for teams who have experienced the cost of a production breaking change that took down multiple consumer services simultaneously, the value is concrete and memorable.

For platform teams managing APIs consumed by external partners or multiple internal teams with independent release cycles, contract-first development is not a nice-to-have. It is a reliability engineering practice as fundamental as having tests, as having CI, as having monitoring. The question is not whether to adopt it but how to sequence the adoption to minimize disruption and maximize the learning curve benefit for the team. Start with oasdiff on a single high-traffic spec as a warning gate, build the team's intuition for what changes are breaking, and then expand the discipline incrementally to the full microservices estate.