What should I use for versioned API documentation?

For versioned API documentation, the best choice depends on your API style and how much automation you want. In most cases, the safest default is:

Recommended default

OpenAPI + a documentation generator
Examples: Swagger UI, Redoc, Stoplight, Scalar

Why this is usually best:

• Widely supported
• Works well for REST APIs
• Easy to version alongside your code
• Can generate interactive docs, clients, and tests
• Good tooling ecosystem

Good options by use case

1. REST APIs

Use:

• OpenAPI 3.x as the spec format
• Swagger UI or Redoc for rendering

Versioning approach:

• Keep one OpenAPI file per API version, e.g.:
  • /docs/v1/openapi.yaml
  • /docs/v2/openapi.yaml
• Or serve versioned docs at:
  • api.example.com/docs/v1
  • api.example.com/docs/v2

2. If you want better design-first workflows

Use:

• Stoplight
• Postman
• SwaggerHub

These are useful if:

• multiple teams collaborate
• you want mocks, design reviews, and governance
• documentation is part of API lifecycle management

3. If you want very polished docs

Use:

• Redoc
• Scalar

These tend to look cleaner than plain Swagger UI and are better for external-facing docs.

4. For GraphQL APIs

Use:

• GraphiQL, Apollo Sandbox, or SpectaQL
• Versioning is usually handled differently than REST, often by schema evolution rather than explicit URL versioning

Best practice for versioned docs

No matter the tool:

• Version the spec itself
• Keep docs in the same repo as the API
• Link each version clearly
• Mark deprecated endpoints
• Document breaking changes and migration notes
• Avoid documenting only the latest version if older versions are still supported

Simple recommendation

If you just want a practical answer:

• OpenAPI + Redoc for external documentation
• OpenAPI + Swagger UI if you want the most familiar interactive docs
• Stoplight if you want a full design-and-documentation platform

If you tell me your stack (REST/GraphQL, language/framework, public vs internal API), I can recommend a specific setup.