Prompt
How do I set up API documentation in CI/CD so the docs update automatically when the spec changes?
Latest observation
A good way to do this is to treat your API spec as the source of truth and generate/publish docs automatically in your pipeline whenever the spec changes.
Recommended CI/CD setup
1) Keep the API spec in version control
Store your OpenAPI/Swagger file, for example:
openapi.yamlopenapi.json
Put it in the same repo as the API code, or in a separate spec repo if you have multiple services.
2) Validate the spec in CI
Add a pipeline step that checks the spec is valid before publishing docs.
Typical checks:
- YAML/JSON syntax
- OpenAPI schema validation
- Linting style rules
Examples:
spectral lint openapi.yamlswagger-cli validate openapi.yamlredocly lint openapi.yaml
This prevents broken docs from being deployed.
3) Generate docs automatically
Use a doc generator such as:
- Redoc / Redocly
- Swagger UI
- Stoplight Elements
- Docusaurus + OpenAPI plugin
- MkDocs + plugin
You can either:
- render the docs dynamically from the spec, or
- generate static HTML and publish it as an artifact or to a docs site.
Static generation is often easier for CI/CD.
4) Publish docs on merge or release
Trigger docs publishing when:
openapi.yamlchanges- main branch is updated
- a release tag is created
Common deployment targets:
- GitHub Pages
- S3 + CloudFront
- Netlify
- Vercel
- internal docs server
- artifact repository
5) Automate versioning
If you version your API:
- publish docs per release version
- keep
latestpointing to the newest stable version - optionally keep older docs available
Example structure:
/docs/latest/docs/v1.2.0/docs/v1.3.0
Example GitHub Actions flow
-
On push to
main:- validate OpenAPI spec
- generate docs
- deploy docs site
-
On pull request:
- validate spec
- optionally build preview docs
Example workflow
name: API Docs
on:
push:
branches: [main]
paths:
- 'openapi.yaml'
- 'docs/**'
pull_request:
paths:
- 'openapi.yaml'
- 'docs/**'
jobs:
validate-and-build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Redocly CLI
run: npm install -g @redocly/cli
- name: Validate spec
run: redocly lint openapi.yaml
- name: Build docs
run: redocly build-docs openapi.yaml -o docs/index.html
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: api-docs
path: docs/
deploy:
if: github.ref == 'refs/heads/main'
needs: validate-and-build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs
Best practices
- Use the spec as the single source of truth
- Fail the build if spec validation fails
- Generate docs on every spec change
- Publish preview docs for PRs so reviewers can see changes
- Keep docs versioned
- Separate stable docs from draft/preview docs
- Add changelog links or release notes
If you want live docs instead of generated static docs
You can host Swagger UI or Redoc and have it fetch the spec file from a URL. Then your CI/CD only needs to deploy the updated spec file. This is simpler if your hosting supports it.
Example:
- docs page is stable
openapi.yamlis updated in the same deployment- UI loads the latest spec at runtime
A practical pattern
A common production setup is:
- PR changes
openapi.yaml - CI validates it
- PR preview docs are generated
- merge to
main - pipeline deploys updated spec + docs to production docs site
- release tags publish versioned docs
If you want, I can also give you:
- a GitHub Actions example,
- a GitLab CI example, or
- a Docker-based docs pipeline.