I recently had to look at API versioning for ASP.NET Core 2.0 APIs for work. We looked at aspnet-api-versioning and contrasted that with Troy Hunt’s You are doing API-versioning wrong […].

We had decided we didn’t want to version controllers but rather the individual actions.

Initial approach

We all went off and looked at various solutions end-to-end and will compare notes tomorrow.

I tried a variation of Troy Hunt’s VersionedRoute attribute – but based on the IActionConstraint attribute for ASP.NET Core – that applies a regular expression to the accept header to determine the version to select. Initial testing showed promise.

Showstopper?

Swashbuckle does not enjoy multiple actions with the same route in the same Swagger document. By using operationfilters to keep versions of the same actions in separate SwaggerDocs we could get the page to load without error.

Hack

By figuring out the highest version of any action in the API I generate one SwaggerDoc for each, including either actions with that specific version – or the highest version of operations that only have lower versioned actions or of course unversioned actions.

That way, if you just load the swagger page – you only see the newest versions. Weirdness only sets in when you try to operate the versions dropdown, but even then it kind of makes sense.