API Documentation in 2026: OpenAPI, Redoc, Mintlify, and Changelog Best Practices

Bad API documentation is a sales problem disguised as a technical problem. Developers who can't figure out your API in 15 minutes don't buy — they leave and find an alternative. The tooling has improved dramatically: Mintlify generates beautiful docs from OpenAPI specs, Redoc renders interactive reference docs, and automated changelog generation ensures your changelog doesn't fall behind the code.

This post covers the full documentation stack for a production API: spec-first design, automated validation, reference docs generation, and changelog automation.

---

Documentation Hierarchy

├── Getting Started Guide          ← Why would I use this? First 15 minutes
│   ├── Quick start (working code in < 5 min)
│   ├── Authentication setup
│   └── First API call
├── Guides / Tutorials             ← How do I accomplish X?
│   ├── Common workflows (end-to-end)
│   ├── Error handling patterns
│   └── Webhooks setup
├── API Reference                  ← What exactly does endpoint X do?
│   ├── Generated from OpenAPI spec
│   ├── Every parameter documented
│   └── Request/response examples
└── Changelog                      ← What changed and when?
    ├── Breaking changes highlighted
    ├── Deprecation notices
    └── Migration guides

---

OpenAPI 3.1 Spec: Best Practices

# openapi.yaml
openapi: "3.1.0"

info:
  title: MyApp API
  version: "2.1.0"
  description: |
    The MyApp API gives you programmatic access to user management, billing,
    and analytics data.

    ## Authentication
    All API requests require a bearer token in the Authorization header:
    ```
    Authorization: Bearer <your_api_key>
    ```

    ## Rate Limits
    - 1,000 requests per minute per API key
    - Bulk endpoints: 100 requests per minute
    - Rate limit headers included in every response

    ## Versioning
    The API uses URL versioning (`/v2/`). Breaking changes increment the major version.
    See the [changelog](/changelog) for migration guides.
  contact:
    name: Developer Support
    email: developers@myapp.com
    url: https://myapp.com/docs
  license:
    name: Proprietary

servers:
  - url: https://api.myapp.com/v2
    description: Production
  - url: https://api.sandbox.myapp.com/v2
    description: Sandbox

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

  schemas:
    User:
      type: object
      required: [id, email, name, createdAt]
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the user
          examples: ["550e8400-e29b-41d4-a716-446655440000"]
        email:
          type: string
          format: email
          description: User's email address (unique)
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: User's display name
        role:
          type: string
          enum: [admin, member, viewer]
          default: member
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the user was created
        # Nullable fields use oneOf in OpenAPI 3.1 (not nullable: true)
        avatarUrl:
          oneOf:
            - type: string
              format: uri
            - type: "null"
          description: URL to user's avatar image

    Pagination:
      type: object
      required: [total, page, perPage, hasNextPage]
      properties:
        total:
          type: integer
          description: Total number of results
        page:
          type: integer
          description: Current page number (1-indexed)
        perPage:
          type: integer
          description: Results per page
        hasNextPage:
          type: boolean

    Error:
      type: object
      required: [error, code, requestId]
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable error code
          examples: ["USER_NOT_FOUND", "INVALID_EMAIL", "RATE_LIMIT_EXCEEDED"]
        requestId:
          type: string
          description: Request ID for support reference
        details:
          type: object
          description: Additional error context (field-level validation errors, etc.)

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "User not found"
            code: "USER_NOT_FOUND"
            requestId: "req_abc123"

    RateLimit:
      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'

security:
  - BearerAuth: []

paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      tags: [Users]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: role
          in: query
          schema:
            type: string
            enum: [admin, member, viewer]
          description: Filter by role
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                type: object
                required: [data, pagination]
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        "401":
          description: Unauthorized — invalid or missing API key
        "429":
          $ref: '#/components/responses/RateLimit'

---

TypeScript Client Codegen from OpenAPI

# Generate TypeScript SDK from OpenAPI spec
npx openapi-typescript openapi.yaml -o src/generated/api.d.ts
# Or: full client with openapi-fetch
npx openapi-typescript openapi.yaml -o src/generated/schema.ts
npm install openapi-fetch

// src/lib/api-client.ts
import createClient from 'openapi-fetch';
import type { paths } from './generated/schema';

const client = createClient<paths>({
  baseUrl: 'https://api.myapp.com/v2',
  headers: {
    Authorization: `Bearer ${process.env.MYAPP_API_KEY}`,
  },
});

// Fully type-safe API call — parameters and response typed from OpenAPI spec
const { data, error } = await client.GET('/users', {
  params: {
    query: {
      page: 1,
      perPage: 20,
      role: 'admin',
    },
  },
});

if (error) {
  console.error(error.error);  // Typed as Error schema
} else {
  console.log(data.data);      // Typed as User[]
  console.log(data.pagination.hasNextPage);
}

---

Automated OpenAPI Validation in CI

# .github/workflows/api-spec.yml
name: API Spec Validation

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'openapi/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI spec
        uses: char0n/swagger-editor-validate@v1
        with:
          definition-file: openapi.yaml

      - name: Detect breaking changes
        uses: oasdiff/oasdiff-action/breaking@main
        with:
          base: origin/main:openapi.yaml
          revision: openapi.yaml
          # Fails if breaking changes detected without API version bump

      - name: Generate TypeScript types
        run: |
          npx openapi-typescript openapi.yaml -o src/generated/schema.ts
          git diff --exit-code src/generated/schema.ts || \
            (echo "Generated types are outdated. Run: npx openapi-typescript openapi.yaml -o src/generated/schema.ts" && exit 1)

---

Mintlify: Developer Portal Setup

# Install Mintlify CLI
npm install -g mintlify

# Initialize docs
mintlify init

// mint.json — Mintlify configuration
{
  "name": "MyApp API",
  "logo": {
    "dark": "/logo/dark.svg",
    "light": "/logo/light.svg"
  },
  "favicon": "/favicon.png",
  "colors": {
    "primary": "#2563EB",
    "light": "#60A5FA",
    "dark": "#1D4ED8"
  },
  "api": {
    "baseUrl": "https://api.myapp.com/v2",
    "auth": {
      "method": "bearer"
    }
  },
  "openapi": "openapi.yaml",
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "authentication", "quickstart", "errors"]
    },
    {
      "group": "Guides",
      "pages": ["guides/webhooks", "guides/pagination", "guides/rate-limits"]
    },
    {
      "group": "API Reference",
      "pages": [
        "api-reference/users/list",
        "api-reference/users/create",
        "api-reference/users/get",
        "api-reference/users/update",
        "api-reference/users/delete"
      ]
    },
    {
      "group": "Resources",
      "pages": ["changelog", "sdks", "support"]
    }
  ],
  "footerSocials": {
    "github": "https://github.com/myorg",
    "twitter": "https://twitter.com/myapp"
  }
}

---

Automated Changelog Generation

# Install conventional-changelog tooling
npm install -D conventional-changelog-cli conventional-changelog-conventionalcommits

# Generate changelog from conventional commits
npx conventional-changelog -p conventionalcommits -i CHANGELOG.md -s

// .commitlintrc.js — Enforce conventional commit format in CI
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // Scope required for API changes
    'scope-enum': [2, 'always', ['users', 'billing', 'webhooks', 'auth', 'analytics']],
  },
};

// Commit format: type(scope): description
// feat(users): add bulk user import endpoint
// fix(billing): correct proration calculation for mid-cycle upgrades
// BREAKING CHANGE: rename `user_id` to `userId` in all responses

# CHANGELOG.md example output

[2.1.0] - 2026-08-13

Features

• users: add bulk user import endpoint (POST /v2/users/bulk) (#234)
• webhooks: add user.deleted event type (#228)

Bug Fixes

• billing: correct proration calculation for mid-cycle plan upgrades (#231)
• auth: token refresh now returns 401 instead of 500 for expired tokens (#229)

---

[2.0.0] - 2026-07-01

⚠️ Breaking Changes

• Renamed user_id to userId in all response bodies
• Removed deprecated GET /v1/users endpoint (use /v2/users)
• Changed pagination from offset/limit to cursor-based

Migration Guide

See v1 → v2 Migration Guide for step-by-step instructions and a compatibility layer for gradual migration.

---

API Documentation Quality Checklist

## Developer Documentation Checklist

### Getting Started
- [ ] Working code example in < 5 minutes (copy-paste to run)
- [ ] Authentication setup covered with actual example
- [ ] Common error responses documented with fix instructions

### API Reference (per endpoint)
- [ ] Description: what does this do and when would you use it?
- [ ] All parameters documented (name, type, required/optional, constraints)
- [ ] Request body with example (realistic, not placeholder data)
- [ ] All response codes documented (200, 400, 401, 403, 404, 422, 429, 500)
- [ ] Response body schema with example
- [ ] Side effects noted (webhooks fired, async operations, rate limit costs)

### Changelog
- [ ] Breaking changes flagged clearly
- [ ] Migration guide for every breaking change
- [ ] Deprecation notices with timeline (not just "this will be removed")
- [ ] Links from changelog to PR or commit for context

### Developer Experience
- [ ] Interactive playground (Mintlify/Redoc/Swagger UI)
- [ ] Code examples in ≥2 languages (TypeScript, Python minimum)
- [ ] SDK published to npm/PyPI
- [ ] Postman collection or Bruno collection available for download

---

Working With Viprasol

We build developer-facing API documentation portals — from OpenAPI spec design and validation pipelines through Mintlify deployment and automated changelog generation.

What we deliver:

• OpenAPI 3.1 spec design and validation CI workflow
• TypeScript SDK generation and npm publishing pipeline
• Mintlify documentation portal setup and deployment
• Automated changelog from conventional commits
• Developer portal with interactive playground and code examples

→ Discuss your developer documentation needs → API development services

---

See Also

• OpenAPI Design and API-First Development
• API Gateway Patterns
• API Versioning Strategies
• gRPC vs REST
• Developer Experience (DX) Metrics