OpenAPI and documentation

The OpenAPI Specification is a standard, language-neutral format for describing an HTTP API in YAML or JSON: its paths, the operations on each, their parameters, request bodies, responses, data schemas and security schemes. It began as Swagger; version 2.0 was donated to the OpenAPI Initiative and renamed, and 3.x is what new APIs use. Since 3.1, its Schema Object is a superset of JSON Schema draft 2020-12, instead of the similar-but-different dialect that 3.0 used.

openapi: 3.1.0
info: { title: Orders API, version: "2.3.0" }
paths:
  /orders/{orderId}:
    parameters:
      - { name: orderId, in: path, required: true, schema: { type: string } }
    get:
      operationId: getOrder
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }
        "404": { description: No such order }

Two rules in that snippet trip people up. Every {orderId} in a path template must be declared as a parameter with in: path — either on the path item (shared by all its operations) or on the operation — and a path parameter must say required: true. And every operationId must be unique across the document, because code generators turn it into a method name.

What one document buys you

A description that tools can read is worth more than prose, because the same file drives:

• reference documentation (Swagger UI, Redoc and many others);
• client SDKs and server stubs from code generators;
• request and response validation at a gateway or in middleware;
• mock servers, so frontend work starts before the backend exists;
• contract tests and breaking-change checks in CI, by diffing the document against the last released one.

1const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];2 3const doc = {4  openapi: "3.1.0",5  paths: {6    "/orders": {7      get: { operationId: "listOrders" },8      post: { operationId: "createOrder" },9    },10    "/orders/{orderId}": {11      parameters: [{ name: "orderId", in: "path", required: true }],12      summary: "A single order",13      get: { operationId: "getOrder" },14      delete: { operationId: "deleteOrder" },15    },16  },17};18 19export function run() {20  const ops = [];21  for (const [path, item] of Object.entries(doc.paths)) {22    for (const m of METHODS) {23      if (item[m]) ops.push(`${m.toUpperCase()} ${path} -> ${item[m].operationId}`);24    }25  }26  return ops;27}

Design-first or code-first

Design-first: write the OpenAPI document, review it like code with the people who will call the API, then implement against it. The contract is agreed before anyone depends on accidental behaviour. Code-first: annotate controllers and generate the document from the code. Faster to start and never out of date with the code — but the API's shape becomes whatever the framework happened to produce. Either way, the document belongs in version control and in CI.

Validation is where the document stops being documentation and starts being enforced:

1const schema = {2  type: "object",3  required: ["sku", "quantity"],4  properties: {5    sku: { type: "string" },6    quantity: { type: "integer", minimum: 1 },7  },8};9 10function typeOf(v) {11  if (Number.isInteger(v)) return "integer";12  if (Array.isArray(v)) return "array";13  return v === null ? "null" : typeof v;14}15 16function validate(body) {17  const errors = [];18  for (const f of schema.required) if (!(f in body)) errors.push(`/${f}: is required`);19  for (const [f, s] of Object.entries(schema.properties)) {20    if (!(f in body)) continue;21    if (typeOf(body[f]) !== s.type) errors.push(`/${f}: must be ${s.type}`);22    else if (s.minimum !== undefined && body[f] < s.minimum) errors.push(`/${f}: must be >= ${s.minimum}`);23  }24  return errors;25}26 27export function run() {28  return [29    validate({ sku: "PEN-1", quantity: 2 }),30    validate({ sku: "PEN-1", quantity: 0 }),31    validate({ quantity: 1.5 }),32  ];33}

Documentation is more than the reference

Generated reference pages answer "what does this field mean". New users also need a quickstart that makes one real call in minutes, an authentication guide, examples for every operation, a catalogue of error types and what to do about each, rate-limit rules, and a changelog with deprecation dates.

Common mistakes

• A hand-maintained document that drifts from the implementation, so generated clients fail against the real API. Test the API against it in CI.
• Path templates with undeclared parameters, or path parameters without required: true; tools reject or misgenerate them.
• Duplicate or missing operationIds, giving generated SDKs clashing or meaningless method names.
• Documenting only the 200 response, so clients learn the error shapes in production.

What interviewers ask

• What is OpenAPI for? — a machine-readable contract that generates docs, clients and mocks, validates traffic, and lets CI detect breaking changes.
• Design-first or code-first? — design-first agrees the contract before implementation; code-first keeps the document in sync with the code; both need the document checked in CI.
• How do you keep docs and the API in sync? — generate one from the other or test the running API against the document, and diff the document on every change.