Controllers marked [ApiVersionNeutral] do not appear in Swagger

[chippiearnold]

I have integrated Swagger to my versioned API successfully and have been playing with creating different versions of controllers. I wanted to mark a particular controller as ApiVersionNeutral, which works fine from my test client, but the controller then disappears from Swagger - understandable, as I can request the version in Swagger and so it makes sense that something without a version doesn't appear.

So, my question is - is there any way to make neutral controllers appear regardless of what version has been requested through Swagger?

[chippiearnold]

Never mind, I think I have worked this out - I need to amend the way my RoutePrefix works, as I currently have the same prefix across different controllers which is a mistake. I will close this issue as I believe this to be user error - sorry!

[commonsensesoftware]

You didn't specify if this was ASP.NET Web API or Core. I did a sanity check and it appears that the Web API version does have a bug that doesn't honor API version neutrality.

One thing that can be confusing about API versioning is that once you enable it, everything has an API version. There is really no such thing as no API version. Despite my effort to use a clear name, I failed. API version-neutral does not mean unversioned. Instead, it means every version (e.g. neutral or I don't care which version). This should mean that a version-neutral API should appear for every known version.

[chippiearnold]

I was just about to re-open, as what I thought I had done wrong hasn't in fact fixed the issue!
To clarify, I'm using ASP.NET Web API (not Core).

To clarify what I'm trying to achieve:

I have a controller called AuditController, which now has a V2 method.
There is another controller called EntityTypesController. Nothing in this has changed with the new version, so I can just append ApiVersion("2.0") and this works fine.

I then considered that, rather than having to append another ApiVersion attribute every time a new version of some other controller is released, if nothing has changed in EntityTypesController then I could simply use [ApiVersionNeutral] - and keep using this until the point at which I need to version the EntityTypesController.

It works fine when I tested this from my test client consuming the API, but I couldn't then see the controller in the Swagger documents - which may be the bug you talk about above.

Hope that adds some clarification!

[chippiearnold]

Just as a further explanation - I'm trying to avoid my clients needing to pass different versions depending on what service call they are making. This is a gateway api, and I essentially want the client to be able to just specify what "version of the API" they are using once, for every request.

In other words, if a client says they are on version 2 and wants audits, they'll get the V2 audit object. But if they then request EntityTypes, event though they will still pass api-version 2 in the request, they will just get the "VersionNeutral" entity types controller - until such point that I have to amend the EntityTypesController, in which case I will remove the ApiVersionNeutral attribute and replace it with specific ApiVersion attributes instead.

I hope I'm making sense(!)

[commonsensesoftware]

For documentation, it's definitely an issue. It was a simple oversight on my part. I'm in the process of working on a fix.

In terms of your approach to address your versioning scenarios, this is a plausible solution. Kind in mind, however, that by going version-neutral the controller will accept any version, even ones that that you don't necessarily want to support. This might be fine now, but it could come back to haunt you. I had that happen with one team. They went from being version-neutral to versioned, which one would think should be ok if the client is passing a version. In that case, the clients were, in fact, passing an API version, but it wasn't a supported API version. It was some arbitrary API version that was being accepted and ultimately broke once a specific API version was required. Be careful with being version-neutral if you think you might ever become versioned - there be dragons.

There are some other alternatives to achieving your goal:

• Use a HttpMessageHandler and set the API version for that specific route very early in the pipeline a la the available, but purposely hidden HttpRequestMessage.SetRequestedApiVersion
• Enable no version to be specified via the AssumeDefaultVersionWhenUnspecified option, create a custom IApiVersionSelector, and hook in up in the API versioning options

The IApiVersionSelector was specifically meant to help address the scenario you are describing. The single method SelectVersion accepts the current HttpRequestMessage and an aggregation of all discovered API versions (so you don't have to do the hard work). You can then choose the best API version given the API version model or some other information from the current request. In your case, it would be the request itself for one specific route. The IApiVersionSelector.SelectVersion method is only called when no API version is specified and implicitly API versioning is allowed.

This approach can be taken to the extreme, which would be to create a version mapping between clients and implemented API versions. Once a client calls for the first time, they are bound to the API version they matched to. From that point forward, they will always get that version. You'd have to write some bits to store this mapping and you'd want to pre-load it some where in the pipeline, but it is possible. If you have external storage holding this mapping, you'll definitely want to do it outside the IApiVersionSelector because it's design is [intentionally] not asynchronous.

If this is something you are interested in pursuing, you can find more information in the API Version Selector topic. Their implementations are pretty simple. Feel free to checkout the source for how to implement your own.

I hope that helps.

[chippiearnold]

Wow that is super helpful, thank you - I will look further into the IApiVersionSelector as you suggest. This is a fairly new api and not yet fully out in the wild, so it will be good to get this right up front.

Thanks again!

[emanuel-v-r]

Hi guys,

Can I find any example on how to expose an ApiVersionNeutral Controller in Swagger?
Sorry guys if this is not the proper place to ask.

Thank you