How do I make API docs update automatically when the spec changes?

The usual way is to make the docs generated from the spec and rebuild them automatically whenever the spec file changes.

Common approach

1. Keep the API spec in source control

   • OpenAPI/Swagger, AsyncAPI, GraphQL schema, etc.

2. Generate docs from the spec

   • Use a docs tool that reads the spec and renders HTML/Markdown/site pages.
   • Examples:
     • OpenAPI: Swagger UI, Redoc, Stoplight, Spectacle
     • GraphQL: GraphiQL, Apollo docs tools
     • AsyncAPI: AsyncAPI Generator / Studio

3. Add a CI/CD step

   • When the spec changes, a pipeline runs:
     • validate spec
     • generate docs
     • publish docs site

4. Trigger on spec changes

   • Set up:
     • GitHub Actions / GitLab CI / Jenkins / CircleCI
     • run on push/PR when openapi.yaml, swagger.json, etc. changes

Example workflow

• Developer edits openapi.yaml
• CI detects change
• CI runs:
  • openapi lint
  • openapi generate docs
• Docs are deployed to a static site or docs server
• Result: docs always match the latest committed spec

Good patterns

• Single source of truth: spec is the source, not hand-written docs
• PR previews: publish temporary docs for each pull request
• Versioned docs: keep docs for v1, v2, etc.
• Fail builds on invalid spec: prevents broken docs

Example with GitHub Actions

name: Update API Docs

on:
  push:
    paths:
      - 'openapi.yaml'
      - '.github/workflows/docs.yml'

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate spec
        run: |
          npx @redocly/cli lint openapi.yaml
      - name: Build docs
        run: |
          npx redoc-cli build openapi.yaml -o docs/index.html
      - name: Deploy
        run: echo "deploy step here"

If you want live auto-updating docs during development

Use a local watcher:

• npm run docs:watch
• a file watcher rebuilds docs whenever the spec file changes

---

If you tell me what spec format you use (OpenAPI, GraphQL, AsyncAPI, etc.) and where you host docs, I can suggest a concrete setup.