api-reference

api-reference

Production patterns for writing, validating, and publishing machine-readable API reference documentation. Covers OpenAPI 3.1, AsyncAPI 2.x, doc generation from code annotations, and consumer-facing reference portals.

OpenAPI 3.1 Document Skeleton

Start from a valid skeleton; fill in the gaps rather than building from scratch.

# openapi.yaml
openapi: "3.1.0"

info:
  title: Acme API
  version: "2.4.0"
  description: |
    REST API for the Acme platform.
    
    **Base URL:** `https://api.acme.io/v2`  
    **Auth:** Bearer token via `Authorization` header  
    **Rate limits:** 1000 req/min per token  
  contact:
    name: Platform Team
    email: [email protected]
    url: https://status.acme.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: https://api.acme.io/v2
    description: Production
  - url: https://sandbox.acme.io/v2
    description: Sandbox (no billing, safe to test)

tags:
  - name: widgets
    description: Create and manage widgets
  - name: auth
    description: Authentication and token management

paths:
  /widgets:
    get:
      operationId: listWidgets
      tags: [widgets]
      summary: List all widgets
      description: |
        Returns a paginated list of widgets owned by the authenticated account.
        Results are sorted by `created_at` descending.
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
        - name: status
          in: query
          schema:
            type: string
            enum: [active, archived, draft]
          description: Filter by widget status
      responses:
        "200":
          description: Paginated list of widgets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WidgetList"
              examples:
                default:
                  $ref: "#/components/examples/WidgetListExample"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"

components:
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

  responses:
    Unauthorized:
      description: Missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: UNAUTHORIZED
            message: "Bearer token is missing or expired"
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the rate limit resets
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: VALIDATION_ERROR
        message:
          type: string
          description: Human-readable error description
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              issue:
                type: string

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []