How do I document multiple versions of the same API?

To document multiple versions of the same API, treat each version as a distinct contract while keeping the shared parts reusable.

Recommended approach

1. Document each version separately

Create a separate section, page, or OpenAPI file for each version, for example:

• /docs/v1
• /docs/v2

or

• openapi-v1.yaml
• openapi-v2.yaml

This makes it clear which endpoints, request/response shapes, and behaviors apply to which version.

2. Highlight what changed

For each version, document:

• added endpoints
• removed endpoints
• changed fields
• changed authentication or error behavior
• deprecated features

A short “What’s new / changed” section is very helpful.

3. Keep common parts shared

If you use OpenAPI or similar tooling, reuse common components where possible:

• schemas
• error models
• auth definitions
• pagination formats

Only version the parts that actually differ.

4. Label versions clearly

Make versioning obvious in:

• the URL path: /v1/orders
• a header: API-Version: 2
• the docs title: Orders API v2

Also note the supported and deprecated versions.

5. Include migration guidance

If v1 and v2 coexist, add a migration guide:

• old field → new field
• old endpoint → new endpoint
• behavioral changes
• timeline for deprecation

6. Make the docs easy to compare

A side-by-side or changelog-style table works well:

Feature	v1	v2
customerName	string	split into firstName and lastName
/orders/{id}	yes	yes
/payments	no	yes

If you use OpenAPI

Common patterns are:

• one spec per version
• one spec with versioned paths and tags
• separate docs grouped by version in your portal

Example:

• openapi-v1.yaml
• openapi-v2.yaml

Good practice

Avoid mixing incompatible versions into a single endpoint description unless the differences are minor. If the behavior or schema changes significantly, document them as separate versions.

If you want, I can also show:

• a sample OpenAPI setup for v1/v2
• a documentation structure template
• how to do this in Swagger UI, Redoc, or GitBook