Swagger integration not working with versioned OData routes vs query parameter

[jimmy3912msncom]

I have integrated successfully with the Microsoft.AspNetCore.OData.Versioning v3.0.0-beta1 package in my service and now I want to enable swagger. My service ONLY supports URL path versioning and not the query filter version. I used the https://github.com/Microsoft/aspnet-api-versioning/tree/master/samples/aspnetcore/SwaggerODataSample sample as a reference and everything works if I use query parameter versioning. Since my actual application uses only URL path formatting and has no support for query parameter versioning support, I tried this out in the sample by editing the Startup.cs by replacing the below two lines:

services.AddApiVersioning( options => options.ReportApiVersions = true );
with

services.AddApiVersioning( options => { options.ApiVersionReader = new UrlSegmentApiVersionReader(); options.ReportApiVersions = true; options.RouteConstraintName = "apiVersion"; });

and
app.UseMvc( routeBuilder => routeBuilder.MapVersionedODataRoutes( "odata", "api", modelBuilder.GetEdmModels() ) );

with
routeBuilder.MapVersionedODataRoutes("odata", "v{apiVersion}", modelBuilder.GetEdmModels());

When I do this the swagger UI doesn't give me an option anymore to specify the version in the URL path so when I try the API, it fails with 404 Not Found since it shows the API as v{version}. This would result in the API call as http://localhost:5000/v{version}/People(1) for example which makes sense to be 404 Not Found.
Is this possible with the Microsoft.AspNetCore.OData.Versioning.ApiExplorer v3.0.0-beta1 package today and if so, how would I configure this to work?

[commonsensesoftware]

There's a couple of small issues here:

1. You don't need to change the route constraint name unless you want something different. The default is already apiVersion.
2. Your route prefix doesn't contain the route constraint, it only contains a route parameter name. The route parameter with the constraint should be in the form of {param-name:constraint-name}; for example {version:apiVersion}.
3. There is a gap in the API Explorer implementation that prevents Swagger generators like Swashbuckle from picking up the default value for a route parameter. When the parameter is present, you need to use a custom IOperationFilter to fill in the default value.
   a. This is not necessary when using the URL segment method and with the API Explorer configured as options.SubstituteApiVersionInUrl = true.

If you have all of this and it's still not working, it's possible that this is an existing bug. I'm very, very close to releasing Beta 2 (the plan is tomorrow), which should contain a number of fixes; especially for OData on ASP.NET Core.

[jimmy3912msncom]

@commonsensesoftware
Thanks for the reply Chris. I made the suggested changes for 1 and 2.

services.AddApiVersioning( options =>
{
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
    options.ReportApiVersions = true;
});
...

routeBuilder.MapVersionedODataRoutes("odata", "v{version:apiVersion}", modelBuilder.GetEdmModels());

The version parameter still doesn't show up in swagger UI. I wasn't clear on the point you made on IOperationFilter.

Should I be implementing a custom one or would you recommend just waiting for Beta 2 tomorrow?

[commonsensesoftware]

It should be the same as the SwaggerDefaultValues used in the example. Do you have that included?

[jimmy3912msncom]

@commonsensesoftware Yes I do. As I mentioned above, I am taking exactly the sample, editing those two lines and running it. Still doesn't work. Thoughts?

[jimmy3912msncom]

@commonsensesoftware Also do you have any samples that works at all with URL path versioning?

[commonsensesoftware]

FYI, this is, in fact, a duplicate of #365. The fix is in and will be released in Beta 2. Things are building now. The new packages should be available tomorrow.

[jimmy3912msncom]

Thanks Chris. I’ll wait for it and try it out :)

[commonsensesoftware]

FYI, Beta 2 has been released. Let me know if you still encounter issues. Thanks.

[jimmy3912msncom]

@commonsensesoftware It works great now thanks alot 👍