OpenAPI & Swagger

One spec, many uses

OpenAPI (formerly Swagger) is a YAML/JSON format describing every endpoint, parameter, request/response shape, and auth requirement. From that single spec you can generate interactive docs, client SDKs, and server stubs.

A tiny slice

Every path documents its methods, parameters, and possible responses.

paths:
  /orders/{id}:
    get:
      summary: Get an order by id
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200': { description: Order found }
        '404': { description: Order not found }

Keep it generated, not hand-copied

Hand-maintained docs drift from the real API within weeks. Where possible, generate the spec from code annotations or tests so it can't silently go stale.