Verträge & Consumer-Driven Testing

"An API is a contract" has been this module's refrain. This lesson makes the contract literal and executable: a machine-readable OpenAPI specification that documents the API precisely, and consumer-driven contract testing that fails your build the moment you make a change that would break a real consumer. Together they turn "don't break the API" from a hope into an automated guarantee.

OpenAPI: the machine-readable contract

OpenAPI (formerly Swagger) is a standard format - YAML or JSON - describing every endpoint, its parameters, request/response schemas, and status codes:

paths:
  /accounts/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Account' }
        '404':
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }

Because it's machine-readable, one spec drives many things: interactive docs (Swagger UI), client SDK generation in any language, server stubs, and request/response validation. Two workflows exist:

• Code-first - annotate your controllers (springdoc-openapi) and generate the spec from the code. Easy, but the spec follows the code.
• Design-first - write the OpenAPI spec first, agree it with consumers, then implement against it. The spec becomes the source of truth and the contract is negotiated before a line of code.

Design-first is powerful for APIs with external consumers: the contract is agreed up front, teams work in parallel against the spec, and drift is caught by validating the implementation against it.

The limit of OpenAPI alone

OpenAPI documents the contract, but it doesn't prove your running service still honors it, nor that a change won't break a specific consumer. A spec can say "returns an Account" while the code quietly drops a field a consumer depended on. You need tests that verify the real interaction - and specifically, tests driven by what consumers actually use.

Consumer-driven contract testing

The key insight: a provider serves many consumers, and each consumer uses only part of the API. A consumer- driven contract (CDC) captures each consumer's actual expectations and verifies the provider against them:

1. The CONSUMER writes a test describing exactly what it needs:
   "When I GET /accounts/42, I expect a 200 with fields `id` and `balance`."
   This generates a CONTRACT (a pact file).

2. The PROVIDER runs that contract against its real implementation:
   the provider's build replays the consumer's expectations and verifies
   its responses still satisfy them.

3. If the provider makes a change that breaks the contract (drops `balance`),
   the PROVIDER's build fails - before the change ever ships.

Tools: Pact (language-agnostic, the standard) and Spring Cloud Contract (JVM-focused). The magic is the direction - the consumer's real needs drive the test, so the provider learns immediately if a change breaks someone. No more "we removed a field we thought nobody used" incidents. And crucially, it tests the actual running provider, not just a document.