openapi-spec

An OpenAPI document is a contract. It is worth having only if it is true, so the first question is always how it stays in sync with the code: generated from annotations or types (code-first), or validated against the implementation in CI (design-first). Pick one and make the check mechanical.

Workflow

Code-first (existing API, typed framework): generate from the source of truth. NestJS (@nestjs/swagger decorators), FastAPI (automatic from Pydantic models), Spring (springdoc), Go (swag, or huma/oapi-codegen design-first), Express or Hono with zod (zod-openapi, @asteasolutions/zod-to-openapi). Commit the generated file and diff it in CI so an undocumented route change fails the build.

Design-first (new API, multiple implementers): write openapi.yaml by hand, generate server stubs and clients from it, and add a contract test (Prism mock or Dredd/Schemathesis against the running server) so the implementation cannot drift.

Either way: spectral lint openapi.yaml in CI with the spectral:oas ruleset plus house rules.

What a complete spec has

• info with a real description, version (semver, bumped with breaking changes), contact.
• servers for each environment, with variables for the base URL.
• securitySchemes (bearer JWT, API key header, OAuth2 flows) and a top-level security default, overridden per operation where public.
• Every operation: operationId (unique, verbNoun, used as the client method name), summary (one line), description (when behaviour needs it), tags (one per resource), parameters with types, formats, constraints, and examples, request body with schema and example, every response the server can send (200/201/204, 400, 401, 403, 404, 409, 422, 429, 500) with a schema.
• One error schema used everywhere (RFC 9457 problem details: type, title, status, detail, instance, plus errors[] for validation).
• Pagination described once (cursor or page/limit) as reusable parameters and a response envelope schema.
• Schemas in components/schemas with required, nullable (3.1: type: [string, "null"]), enum, format (date-time, uuid, email, uri), minimum/maxLength, readOnly for server-set fields, example or examples on each.
• deprecated: true with a description saying the replacement and the removal date.

Design rules that show up in the spec

• Resource nouns, plural, kebab-case paths: /api/v1/order-items/{orderItemId}.
• Ids as opaque strings (format: uuid when true); never expose sequential integers unless they are the public key.
• Filtering, sorting, and field selection as query parameters with documented syntax.
• Idempotency: PUT and DELETE idempotent by definition; POST creates take an Idempotency-Key header when retries are expected.
• Versioning in the path or an Accept header, one scheme, stated in info.description.
• Timestamps ISO 8601 UTC; money as integer minor units plus a currency code, never floats.

Reviewing an existing spec

1. List the routes the code actually serves (framework route table, grep for the router) and diff against paths. Undocumented and phantom routes are the first findings.
2. For each operation, call it (or read the handler) and compare the real response shape and status codes with the spec.
3. Run spectral lint; fix errors, evaluate warnings.
4. Check examples validate against their schemas (openapi-examples-validator or Spectral's oas3-valid-media-example).
5. Generate a client (openapi-generator-cli, openapi-typescript) and read the output; awkward names reveal missing operationIds and inline schemas that should be components.

Minimal skeleton

openapi: 3.1.0
info: { title: Orders API, version: 1.2.0, description: ... }
servers: [{ url: https://api.example.com/v1 }]
security: [{ bearerAuth: [] }]
tags: [{ name: orders }]
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      tags: [orders]
      parameters: [{ $ref: '#/components/parameters/Cursor' }, { $ref: '#/components/parameters/Limit' }]
      responses:
        '200': { description: A page of orders, content: { application/json: { schema: { $ref: '#/components/schemas/OrderPage' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
components:
  securitySchemes: { bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT } }
  parameters: ...
  responses: ...
  schemas: ...

Keep the file split with $ref to components/ files once it passes a thousand lines, and bundle for publishing (redocly bundle).