OpenAPI Contract

An OpenAPI contract is a machine-readable description of an HTTP API that drives documentation, SDK generation, validation, and drift checks in CI.

api

Definition

OpenAPI is a specification format for describing HTTP APIs, including paths, operations, parameters, schemas, and security, so tools can generate docs and clients and contracts can be diffed and tested automatically.

Context and scope

Use it when multiple teams, SDKs, or gateways consume the same API and the description must stay aligned with the implementation.

Common misconceptions

OpenAPI is just documentation; it also drives code generation, mock servers, and CI diff checks
A generated spec stays accurate forever; without validation in CI, specs drift from code
Schema validation replaces business validation; formats and ranges still need domain rules

Anti-patterns

Hand-maintaining a spec that is never validated against live responses
Shipping breaking changes without diffing the spec
Publishing a giant spec with no examples or error models

Related concepts

Related examples

Authoritative source

https://spec.openapis.org/oas/latest.html

How it works

An OpenAPI document describes servers, paths, operations, parameters, request bodies, responses, and reusable schemas. Tooling reads the document to render reference docs, generate typed clients, spin up mock servers, and validate traffic. In CI, a diff tool compares the proposed spec with the published one and flags removals, tightened constraints, or changed types as breaking.

paths:
  /orders/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }

The spec is a contract only if it is enforced. Design-first teams review the document before implementation; code-first teams generate it from annotations and then lint it.

When to use it

Use OpenAPI when several consumers depend on one HTTP API, when SDKs and gateways are generated from a description, or when partner integrations need an unambiguous reference. It is also the basis for contract tests that keep producer and consumer expectations aligned.

Trade-offs

Writing and maintaining a complete spec is real work, and examples plus error models are often skipped. Generated specs can be technically valid but semantically vague. Spec drift is the main risk: if CI does not compare the document with implementation and responses, the contract becomes fiction. Versioning the document alongside the API prevents surprises.

Example and misconceptions

Teams sometimes treat a 200 response schema as proof of correctness. It only says the shape is allowed; business rules such as refund limits still belong in code. Pair the spec with contract tests and runtime validation at the edge.

Related concepts: Contract Testing, API Versioning, and API Gateway.