Documenting your API with OpenAPI

Why document an API?

An API is only useful if people can call it correctly. The mobile developer, the frontend team, a partner company and you six months from now all need to know: which URL, which method, which fields, which headers, and what can go wrong. Without docs, they guess, ask on chat all day, or read your source code.

OpenAPI: one file that describes the API

OpenAPI is a standard format for describing HTTP APIs. It used to be called Swagger, and many people still use that name. You write (or generate) one file, usually openapi.yaml. It lists every path, the methods on each path, the parameters, the request body and every possible response with its status code.

openapi: 3.1.0
info:
  title: Notes API
  version: 1.2.0
paths:
  /api/notes/{id}:
    get:
      summary: Get one note by id
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: The note
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Note' }
        '404':
          description: No note with this id
components:
  schemas:
    Note:
      type: object
      required: [id, title]
      properties:
        id: { type: integer, example: 7 }
        title: { type: string, example: Pay electricity bill }

YAML is a text format that uses indentation (spaces) to show what belongs inside what. A schema describes the shape of data: which fields, their types, and which are required. $ref points to a schema defined once under components, so you do not repeat it.

Tools that turn the spec into a website

Show examples and document errors

Readers copy examples more than they read field lists. For each endpoint, show one full request and the real response. Then list the errors: which status code, when it happens and what the body looks like. Use the same error shape everywhere, for example { "error": { "code": "NOTE_NOT_FOUND", "message": "..." } }.

curl -X POST https://api.example.com/v1/notes \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Call Priya"}'

HTTP/1.1 201 Created
{ "id": 12, "title": "Call Priya", "pinned": false }

Errors:
400 VALIDATION_FAILED  title is missing or longer than 100 characters
401 UNAUTHORIZED       missing or expired token
429 RATE_LIMITED       more than 60 requests per minute

Versioning, changelog and deprecation

• Version: put a major version in the URL (/v1/notes) or a header. Adding a new optional field is safe. Removing or renaming a field breaks apps, so it needs a new major version.
• Changelog: a dated list of every change, newest first, for example "2026-10-01: added pinned field to Note".
• Deprecation: when an endpoint will go away, mark it deprecated: true in the spec, announce a date, and send a Deprecation or Sunset header in responses so clients get a warning.
• Keep the old version running for a fair time. Mobile apps on old phones may not update for months.