How do I build API documentation from OpenAPI in my CI pipeline?

A common CI pattern is:

1. Keep your OpenAPI spec in the repo
2. Validate it in CI
3. Generate docs from it
4. Publish the generated site as a build artifact or deploy it
5. Fail the pipeline if the spec or generated docs are out of date

Typical pipeline flow

1) Validate the OpenAPI spec

Run a linter/validator so broken specs fail fast.

Examples:

• Spectral for linting rules
• openapi-cli or swagger-cli for validation

Example:

npx @stoplight/spectral-cli lint openapi.yaml
npx swagger-cli validate openapi.yaml

---

2) Generate documentation

Popular generators:

• Redoc / Redocly
• Swagger UI
• Docusaurus + OpenAPI plugin
• OpenAPI Generator for some doc outputs
• ReDocly CLI for static docs sites

Example using Redocly:

npx @redocly/cli build-docs openapi.yaml -o docs/index.html

Example using Swagger UI static assets:

• Generate or bundle the spec
• Serve it with a static Swagger UI build

---

3) Publish docs

Common destinations:

• GitHub Pages
• Netlify / Vercel
• S3 + CloudFront
• Internal artifact store
• GitLab Pages

If you only need docs for the build output, upload them as a CI artifact.

---

Example GitHub Actions workflow

This example:

• validates the spec
• generates docs
• uploads the docs as an artifact

name: Build API docs

on:
  push:
    branches: [main]
  pull_request:

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install tools
        run: npm install -g @stoplight/spectral-cli @redocly/cli swagger-cli

      - name: Validate OpenAPI
        run: |
          spectral lint openapi.yaml
          swagger-cli validate openapi.yaml

      - name: Generate docs
        run: |
          redocly build-docs openapi.yaml -o dist/index.html

      - name: Upload docs artifact
        uses: actions/upload-artifact@v4
        with:
          name: api-docs
          path: dist

---

Example GitLab CI

stages:
  - validate
  - docs

validate_openapi:
  stage: validate
  image: node:20
  script:
    - npm install -g @stoplight/spectral-cli swagger-cli
    - spectral lint openapi.yaml
    - swagger-cli validate openapi.yaml

build_docs:
  stage: docs
  image: node:20
  script:
    - npm install -g @redocly/cli
    - redocly build-docs openapi.yaml -o public/index.html
  artifacts:
    paths:
      - public

---

Best practices

Keep docs generation deterministic

• Pin tool versions
• Avoid relying on network calls during generation
• Commit the source spec, not the generated docs, unless you intentionally want static output checked in

Add a “docs drift” check

If you generate docs into a tracked directory, compare generated output to the repo and fail if there are changes.

Example:

npm run generate:docs
git diff --exit-code

Separate validation from generation

Validation should fail quickly; generation can be a later step.

Version your docs

If your API has versions, generate docs per version:

• /v1
• /v2

---

Recommended setup for most teams

If you want a simple, modern setup:

• Spectral for linting
• Redocly for static docs generation
• GitHub Actions or your CI of choice to validate and publish

---

A practical minimal script

Add to package.json:

{
  "scripts": {
    "lint:openapi": "spectral lint openapi.yaml && swagger-cli validate openapi.yaml",
    "build:docs": "redocly build-docs openapi.yaml -o dist/index.html"
  }
}

Then in CI:

npm ci
npm run lint:openapi
npm run build:docs

---

If you want, I can give you a ready-to-copy CI config for GitHub Actions, GitLab CI, Jenkins, or CircleCI, or recommend the best doc generator for your stack.