How do I set up an OpenAPI docs generator to sync automatically from Swagger and keep docs versioned?

A good way to do this is to treat Swagger/OpenAPI as the source of truth, then make your docs pipeline:

1. Export or generate an OpenAPI spec from Swagger/code
2. Validate and version that spec in CI
3. Publish docs automatically from that versioned spec

Recommended setup

1) Use a single OpenAPI source

If you already have Swagger annotations or a Swagger UI setup, make sure the app can emit an openapi.json or openapi.yaml endpoint.

Common options:

• Swagger annotations in code → generate OpenAPI on build/runtime
• Existing Swagger UI → export the spec from the /swagger.json or /openapi.json endpoint
• Static spec file → checked into repo and updated during release

2) Automate syncing in CI

Have a pipeline step that:

• fetches the latest OpenAPI spec
• compares it with the versioned spec in git
• fails if there’s drift, or auto-commits the updated file

Example flow:

• npm run generate-openapi or docker run ...
• output to openapi/current.yaml
• validate with swagger-cli validate or spectral lint
• if changed, create a PR or tag release

3) Version the docs

Keep docs versioned by:

• storing specs in versioned directories:
  • docs/openapi/v1.0.0/openapi.yaml
  • docs/openapi/v1.1.0/openapi.yaml
• or tagging releases and publishing docs from tags
• or generating docs per branch/release and hosting them separately

Good practice:

• SemVer the API spec
• only bump major on breaking changes
• publish docs for each released version

4) Publish docs automatically

Use a static docs generator or hosted viewer:

• Redoc / Redocly
• Swagger UI
• Stoplight
• Scalar

Pipeline example:

• spec changes merged to main
• CI validates spec
• CI builds docs
• CI deploys to:
  • GitHub Pages
  • S3 + CloudFront
  • internal docs site

Example CI workflow

Pseudo-flow:

steps:
  - checkout
  - install deps
  - generate openapi spec
  - validate spec
  - compare against repo version
  - if changed on release branch:
      package docs
      deploy docs

A practical structure

repo/
  api/
    src/
  openapi/
    v1.0.0.yaml
    v1.1.0.yaml
  docs/
    build/

Tools you can use

• Swagger/OpenAPI generation: swagger-jsdoc, springdoc-openapi, Swashbuckle, fastapi, drf-spectacular
• Validation: Spectral, swagger-cli
• Docs rendering: Redoc, Swagger UI, Scalar
• Version hosting: Git tags, GitHub Pages, S3, Netlify

Best-practice recommendation

If you want minimal manual work:

• generate OpenAPI spec during CI
• validate it
• commit the spec to a specs/ directory per release
• deploy docs from that versioned spec
• make main auto-publish a “latest” docs version and release tags publish fixed versions

If you want, I can give you:

1. a GitHub Actions example,
2. a Docker-based setup, or
3. a setup tailored to your stack (Node, Java, Python, .NET, etc.).