OpenAPI not working with version interleaving within single controller about aspnet-api-versioning HOT 3 CLOSED

Thanks a lot for the quick fix! Haven't been able to take it for a spin yet (been busy visiting a conference this week), but I'm sure I will like it :). Thanks again, and keep up the good work!

from aspnet-api-versioning.

Indeed this is an issue and I've been able to reproduce the conditions. Interestingly, it appears that this behavior has always existed or, at least, certainly for a long time, but has not been reported. Version interleaving with OpenAPI is meant to be supported and it partially is. There is clearly a missing edge case where an overlapping API path will produce a duplicate entry when an action is implicitly matched and is not discarded if an explicitly matched action supersedes it. This is a 🐞 and I've come up with a remedy. As you noted, this behavior does not affect routing, which uses the same implicit matching rules, but is implemented completely differently.

The IApiVersionSelector currently plays no role in documentation. The primary reason for this is because there will be no current HTTP request, which may be necessary for the selector to do its job. It is an open question as to what the expectation of the selector is when there is no useful information in the HTTP request. By contract, null cannot be returned. Providing an empty HTTP request might be sufficient for the purposes of documentation. Some additional enhancements are being discussed in #1009 which might affect the future direction on taking advantage of IApiVersionSelector this way.

The default behavior for the documented api-version parameter is that the first occurrence is required and all other occurrences are optional. Given that there can be more than one location that an API version can appear, that is a sensible default. Although the IApiVersionSelector is not used, if AssumeDefaultVersionWhenUnspecified = true and corresponding ApiVersion equals ApiVersioningOptions.DefaultApiVersion, then the first occurrence will also be optional. This is obviously problematic when not all of the APIs use the same default API version and the IApiVersionSelector is also not used. The only exception is when versioning by URL segment. In this case, the API version parameter is always required because it is part of the path. In addition, any other defined API version location no longer makes sense as you'd still have to specify the path parameter. In retrospect, I suppose the same thing is true when combining other API version locations, which really need to be mapped as One Of, but OpenAPI does not support that concept such as one of: header(api-version) | query(api-version). There is one other slight variant for version-neutral APIs. A version-neutral API can have a parameter, but it isn't required. The API Explorer options let you configure whether this is documented. By default, the API version parameters for version-neutral APIs are omitted.

The immediate workaround is to explicitly use [MapToApiVersion] or use a convention if you don't/can't use attributes. It's inconvenient, but it will unblock you while I work on the fix. I'm experimenting on what it would look like and how things would work if the IApiVersionSelector is used for API Exploration.

from aspnet-api-versioning.

Explicit mappings will now supersede implicit mappings so that problem is fixed.

ApiExplorerOptions now has an IApiVersionSelector ApiVersionSelector { get; set; } property. The default value will use DefaultApiVersion, which was the same as the original behavior. However, in all practical use cases, it will derive the value from ApiVersioningOptions.ApiVersionSelector, which will likely have the same behavior. This gives you the option to configure it once for both. Crucially, you can still explicitly set ApiExplorerOptions.ApiVersionSelector. This is important so that you can use a different IApiVersionSelector for documentation than you might in an actual request pipeline (e.g. an escape hatch). The supplied HTTP request is always empty so it's not useful for documentation.

Enjoy the conference. 😉

from aspnet-api-versioning.