API / Swagger Interview questions
How do you version a REST API documented with Swagger?
OpenAPI itself doesn't prescribe one specific API versioning strategy — that's an API design decision separate from the documentation format — but whichever strategy is chosen needs to be reflected consistently in the spec so the documentation matches actual API behavior.
| Strategy | How it Shows Up in the Spec |
| URI versioning (/v1/users) | Version embedded directly in the paths themselves |
| Header versioning | A documented header parameter, e.g. Accept-Version |
| Query parameter versioning | A documented query parameter, e.g. ?version=2 |
| Content-type versioning | Distinct media types per version in the content map, e.g. application/vnd.api.v2+json |
Separately, the document's own info.version field tracks the version of the API definition itself, which teams commonly bump using semantic versioning conventions as the API evolves, independent of whichever in-URL or in-header versioning scheme the API uses for its actual endpoints.
A practical pattern for URI versioning is maintaining entirely separate OpenAPI documents per major version (one for /v1, one for /v2) once the two versions diverge significantly, rather than trying to cram both into one increasingly complicated spec with conditional logic that OpenAPI has no clean way to express.
More Related questions...
