OpenAPI contract testing for REST services

An OpenAPI document is not documentation. It is a contract, and a contract that can be executed is worth far more than a contract that can only be read.

This guide covers the checks that make the document executable, how to structure it so the checks are meaningful, and — importantly — what a contract still cannot prove.

The document is the test

The value of writing the interface in OpenAPI is that the same document drives four checks with no extra work.

Schema conformance

Every response the service actually returns is validated against the schema its operation declares. This catches the majority of real integration defects: a field that changed type, a required field that stopped being sent, a value outside an enum, a nested object that grew an unexpected field.

RefundResult:
  type: object
  required: [orderId, amount, currency, status]
  additionalProperties: false
  properties:
    orderId: { type: string }
    amount: { type: number, format: decimal }
    currency: { type: string, enum: [EUR, USD, GBP] }
    status: { type: string, enum: [refunded, partially_refunded] }

additionalProperties: false matters more than it looks. Without it, a service that starts sending a new field passes validation, and the consumer that is strict about unknown fields breaks — while your contract test suite stayed green. Turn it on unless you genuinely intend the schema to be open.

Example validation

Every example in the document is validated against the schema it sits under. This is nearly free and catches a surprising amount: examples copied from an older version of the API, hand-written and never executed, quietly wrong.

It also matters for humans. Examples are what most readers actually look at. An example that does not satisfy its own schema is worse than no example.

Breaking-change detection

The document is diffed against the previous version. The changes that break consumers are well known, and the check is a matter of encoding them:

Change Breaking?
An operation is removed Yes
A request field becomes required Yes
An accepted type is narrowed Yes
An enum value is removed Yes
A response status code is removed Yes
A response field becomes required Yes
A field’s type is widened Sometimes — depends on the consumer
A new optional request field is added No
A new response field is added Only if consumers reject unknown fields
A new operation is added No

The "sometimes" row is why the check should be able to be waived per operation, with the waiver recorded. A deliberate break is legitimate — but it should be a decision, visible in the completion map, not a surprise.

Consumer-driven contracts

Where a consumer has stricter expectations than the provider’s schema — a required field the provider considers optional, a specific enum subset — those expectations are recorded as a consumer contract and checked against the provider.

This is the part most teams skip, and it is where the real integration failures live. A provider’s schema says status: string. The consumer requires status to be one of three values. The provider’s own tests pass; the consumer breaks.

Structure the document so the checks bite

Every operation has a stable operationId. It is the join key between the interface and the behaviour, and the thing a scenario references. A renaming operationId is a breaking change, and the check should say so.

Every operation declares its failures. A contract that documents only the success response is not a contract.

responses:
  '200':
    description: Refund granted
  '404':
    description: Order not found
  '422':
    description: Refund refused for this order

Schemas are named and reused. $ref to components/schemas keeps the document readable and makes the reuse visible. A schema that appears inline in three places is three schemas that will drift.

Constraints are expressed, not described. enum, pattern, minimum, maxLength are executable. A comment saying "must be a positive amount" is not.

format is used for the formats that matter. date-time and uuid catch real errors. email catches fewer than people expect.

What the contract cannot prove

A schema constrains shape. It says nothing about meaning.

A perfectly conformant response can still be wrong: the right fields with the wrong values, a 200 where a 409 was owed, a valid amount that is not the order total. No amount of schema validation catches that, because a schema has no way to say "the refund amount must equal the order total".

The contract proves the shape of the response. Behaviour proves the meaning. A specification with only an OpenAPI document has a gap exactly where the business rules live, which is why the platform pairs the two formats and checks them against each other — see cross-format consistency.

Adopting contract testing on an existing service

If you already have a service and a consumer that is not on speaking terms, this is a workable order:

  • Generate the document from the running service. Tools like openapi-diff and springdoc can infer it. It will be incomplete and slightly wrong.
  • Run contract tests against the current implementation. This produces a baseline of what the service does today, including the parts nobody intended.
  • Read the failures. This is where the value is: the inferred document and the implementation disagreeing is a list of undocumented behaviour.
  • Decide, per disagreement, which is right. Some are the implementation being wrong; some are the document being wrong; some are undocumented behaviour you want to keep.
  • Commit the corrected document, then start writing scenarios for the behaviour the document cannot express.

Step 3 is the one people skip, and it is the one that produces the value. The point of adopting contract testing on an existing service is not to produce a document — it is to find out what the service actually does.

Next