Documenting an API

Why it matters

Nobody can use an API they cannot understand. A front-end developer needs to know which routes exist, what to send, and what comes back, including the errors. Writing that down in a chat message or a wiki page goes stale the first time a route changes. The OpenAPI SpecificationThe industry-standard, machine-readable format for describing an HTTP API in YAML or JSON. is the industry-standard, machine-readable way to describe an HTTP API. One file can power interactive docs, generate client code and mock servers, and even validate requests in tests.

OpenAPI and Swagger

The names are often used interchangeably:

• OpenAPI is the specification, maintained by the OpenAPI Initiative under the Linux Foundation. Version 3.0 and 3.1 are in wide use today.
• SwaggerThe original name of the specification, now a family of tools such as Swagger Editor and Swagger UI. was the original name of the specification (up to version 2.0) and is now the name of a set of tools from SmartBear: Swagger Editor, Swagger UI and others.

So you write an OpenAPI document, and you might view it with Swagger UI, Redoc or Scalar.

The shape of an OpenAPI document

An OpenAPI document is YAML or JSON. Here is a small, complete one for a course API:

openapi: 3.1.0
info:
  title: Courses API
  version: 1.0.0
  description: Read and create courses.
servers:
  - url: http://localhost:3000
paths:
  /courses/{id}:
    get:
      summary: Get one course
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: The course
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Course"
        "404":
          description: No course with that id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /courses:
    post:
      summary: Create a course
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewCourse"
      responses:
        "201":
          description: Created
        "400":
          description: Validation failed
components:
  schemas:
    Course:
      type: object
      required: [id, title, level]
      properties:
        id: { type: integer }
        title: { type: string }
        level: { type: string, enum: [beginner, intermediate, mid-level] }
    NewCourse:
      type: object
      required: [title, level]
      properties:
        title: { type: string, minLength: 1, maxLength: 100 }
        level: { type: string, enum: [beginner, intermediate, mid-level] }
    Error:
      type: object
      properties:
        error: { type: string }

Reading it top to bottom:

• info names and versions the API.
• servers lists base URLs.
• paths lists every route. Under each path is one key per HTTP method. Path parameters use braces: {id}, not Express's :id.
• parameters describes path, query and header inputs, each with a schema.
• requestBody and responses describe bodies by content type. Response keys are status codes, quoted as strings.
• components/schemas holds reusable shapes, referenced with $ref. Schemas use JSON Schema keywords such as type, required, enum, minLength and maximum.

Design-first or code-first

Teams generate the document in one of two ways:

• Design-firstWriting and agreeing on the OpenAPI document before implementing the API.: write the OpenAPI file, agree on it with front-end and mobile developers, then implement it. Good when several teams build in parallel.
• Code-firstGenerating the OpenAPI document from annotated routes or schemas in the code.: annotate your routes or schemas and generate the document from code. Some validation libraries can export their schemas as JSON Schema or OpenAPI, so your validation and your docs cannot drift apart.

Either way, keep the document in the same repository as the code and update it in the same pull request as the route change.

What good API docs include

The specification is the reference. Add a short guide next to it that covers:

• Authentication: how to get a session or token, and how to send it. Describe this in OpenAPI with securitySchemes.
• A quick start: one curl command that works.
• Errors: the error body shape and what each status means.
• Limits: page sizes, rate limits, body size.
• Change policy: how versions and deprecations are announced.

Never put real credentials, internal hostnames or production data in examples. Use example.com addresses and obviously fake tokens.

Common mistakes

• Documenting only the 200 response and leaving out errors.
• Docs that drift from the code because nobody updates them in the same change.
• Using Express-style :id in OpenAPI paths instead of {id}.
• Real secrets or customer data in examples.
• No required lists, so every field looks optional.

Quick recap

• OpenAPI is the standard description of an HTTP API; Swagger is a family of tools for it.
• A document has info, servers, paths (methods, parameters, request bodies, responses) and reusable components.
• Document every status code a route can return, with its body shape.
• Keep the document in the repo and change it in the same pull request as the code.

Try it: the Do tab has you write and validate an OpenAPI document for two routes, using the free online Swagger Editor or a local preview.