OpenAPI and Contract-First Development

An OpenAPI document describes endpoints, schemas, auth and errors. In contract-first development, teams review the spec before coding; then generate documentation, mock servers for frontend work, typed clients/SDKs, and validate requests/responses in tests. Lint specs (Spectral) for style rules and detect breaking changes in CI (oasdiff).

openapi: 3.1.0
info: { title: Orders API, version: 1.4.0 }
paths:
  /v1/orders/{id}:
    get:
      operationId: getOrder
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { content: { application/json: { schema: { $ref: "#/components/schemas/Order" } } } }
        "404": { content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } } }
components:
  schemas:
    Order:
      type: object
      required: [id, status, total]
      properties:
        id: { type: string }
        status: { type: string, enum: [pending, paid, shipped, cancelled] }
        total: { $ref: "#/components/schemas/Money" }

Common pitfalls

• Specs written after the fact and drifting from behavior.
• No breaking-change detection in CI.
• Undocumented error responses.

Key points

• Review contracts before building
• Generate mocks, clients and docs
• Lint and diff specs in CI

Further reading: OpenAPI Specification