0

I read tons of documentation about pros and cons of URI versioning against Header (media type) versioning (Best practices for API versioning?).

If I want to chose the media type versioning what's the best way to document my API? I'm using Swagger (2.0) and I looked also into OpenAPI 3.0 but I couldn't find an easy and clear way to exposes different versions for the same endpoint.

I'd like to have a clear and easy understandable way to share my API definitions with my integrators.

Simone
  • 29
  • 3
  • How do the endpoint versions actually differ? Do they differ only with request/response schema, or also query parameters? – Helen Feb 10 '20 at 17:37
  • They can differ in many ways. For example a new version requires a different body (in case of POST or PUT) or require more parameter or the semantic can change. To me it isn't relevant how they can differ it's more how to handle the versioning in Swagger/OpenAPI and make it clear to the end users of the APIs. So far you can just version the full Swagger/OpenAPI definition but not a single endpoint/method – Simone Feb 11 '20 at 08:01

0 Answers0