What is API contract testing, and how does an OpenAPI/Swagger spec fit into your development and testing workflow?

#Why interviewers ask this

Every team says its API is "documented," and almost every team has watched that documentation drift out of sync with the actual code within a few sprints. Asking about contract testing checks whether a candidate has actually shipped an API that other teams depend on — because the failure mode contract testing exists to prevent (a frontend team building against a Postman collection from three releases ago, or two backend services disagreeing about whether a field is nullable) is one you only learn to fear after living through the incident it caused.

#The gap between unit tests, integration tests, and reality

Unit tests verify your code does what you told it to. End-to-end integration tests verify two real services agree, but only by actually running both of them together — usually in a shared staging environment that every team fights over, that is slow to spin up, and that fails for reasons unrelated to your change (someone else's service is down, a shared database has stale seed data). Contract testing sits deliberately between the two: it verifies that a service's real inputs and outputs conform to an agreed-upon contract, in each team's own CI pipeline, independently, without ever needing both real systems running at once. A consumer can validate against the contract with a mock; a provider can validate its real responses against the same contract, and if both pass, integration in staging is a formality instead of a discovery process.

#Two flavors, and when each wins

"Contract testing" covers two related but distinct practices:

Neither replaces the other outright — plenty of mature platform teams run an OpenAPI spec as the public contract and a handful of Pact contracts for their highest-value internal consumers, because the two catch different classes of drift.

#OpenAPI as more than documentation

Once an OpenAPI document exists and is treated as the source of truth — written before or alongside the implementation, not reverse-engineered from it afterward — it stops being documentation and starts driving the workflow in several concrete ways: a mock server (tools like Prism can serve realistic fake responses straight from the spec) lets frontend work start before the backend endpoint exists; Swagger UI or Redoc renders always-current interactive docs directly from the same file, so there's only one artifact to keep accurate; client SDKs and server stubs can be code-generated from it in multiple languages; and — the part that actually earns it the name "contract" — a validating middleware or a dedicated test suite can assert that every real request and response your service handles conforms to the schema, failing the build the moment implementation and spec disagree.

openapi: 3.0.3
info:
  title: Orders API
  version: 1.2.0
servers:
  - url: https://api.shop.example/v1
paths:
  /orders/{orderId}:
    get:
      summary: Retrieve an order by id
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            pattern: '^o_[a-z0-9]{6,}$'
      responses:
        '200':
          description: Order found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              example:
                id: o_9f8e7d
                status: pending
                total: 42.50
                items:
                  - sku: ABC123
                    qty: 2
        '404':
          description: No order with that id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /orders:
    post:
      summary: Create a new order
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [items]
              properties:
                items:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required: [sku, qty]
                    properties:
                      sku:
                        type: string
                      qty:
                        type: integer
                        minimum: 1
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      required: [id, status, total, items]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, paid, shipped, cancelled]
        total:
          type: number
          format: float
        items:
          type: array
          items:
            type: object
            required: [sku, qty]
            properties:
              sku:
                type: string
              qty:
                type: integer
                minimum: 1
    Error:
      type: object
      required: [message]
      properties:
        message:
          type: string

#Enforcing it in CI, not just describing it

A spec nobody checks against reality is a promise with no consequence for breaking it. The way teams make OpenAPI a real contract test is by running the actual service and validating its real responses against the schema on every build:

Wrap long lines
// contract.test.js — fails the build the moment implementation drifts from the published spec
import request from "supertest";
import jestOpenAPI from "jest-openapi";
import app from "../src/app";

jestOpenAPI("./openapi.yaml");

test("GET /orders/:id matches the published contract", async () => {
  const res = await request(app).get("/orders/o_9f8e7d");
  expect(res.status).toBe(200);
  expect(res).toSatisfyApiSpec();
});

test("POST /orders rejects a missing sku per the contract", async () => {
  const res = await request(app)
    .post("/orders")
    .send({ items: [{ qty: 2 }] });
  expect(res.status).toBe(400);
});