Guidance Needed: How to resolve issues

[mhsimkin]

Hi. I'm looking for some guidance on how to go about determine why the following are happening and how to resolve.

Environment: .NET 6, Windows Service, hosting Kestrel.

1. IApiVersionDescriptionProvider.ApiVersionDescriptions only lists one version and that is version 1.0. However, I've only indicated that my API is version 2 using the ApiVersionAttribute on my controller class.

The controller class is in a class library.

2. api-supported-versions and api-deprecated-versions headers are not returned.

I reviewed what was done in the OpenApiExample project and adapted that to my code base.

Thank you for your help.

-marc

[commonsensesoftware]

Can you share a little about the configuration setup and your controller? There are couple of reasons this might be happening, but I need just a bit more information to ensure I give you the correct answer.

[mhsimkin]

Hi @commonsensesoftware.

Thank you for responding.

I just resolved both my issues. I didn't include a call to AddMvc() after the call to AddApiVersioning().

I had assumed, and I was wrong, that the AddMvc() call was the Microsoft extension method, which I didn't need as I'm just using the WebApi and not serving views.

However, now I have another questions. I am using URL versioning. When I look at the actions in Swagger, it shows that a query string parameter specifying the version is required. See the attached image.

Is there a way to disable query string versioning? If not, will I need to intercept the openapi generation to remove the query string parameter?

Thank you.

-marc

[commonsensesoftware]

Glad you got it working. The IServiceCollection extension methods were refactored in 6.0 to wrap around IApiVersioningBuilder to make all API Versioning related extensions shorter and more easily identifiable. AddMvc is new in 6.0. The reason that it was introduced is because when API Versioning is used for Minimal APIs, you don't need any part of MVC (Core). The design is meant to be Pay for Play and limit dependencies to the fewest possible. 😉 To be clear, IApiVersioningBuilder.AddMvc is not the same as IServiceCollection.AddMvc.

IApiVersionReader instances can be composed together via ApiVersionReader.Combine so that applications can accept an API version from multiple locations. The default configuration is:

ApiVersionReader.Combine( new QueryStringApiVersionReader(), new UrlSegmentApiVersionReader() );

This covers 99% of the cases as a sensible default value. However, since it will allow an API version to be specified via query string and/or URL segment, that is probably not want you want; especially for documentation. Simply updating the configuration to only one type of reader will solve this issue:

services.AddApiVersioning( options => options.ApiVersionReader = new UrlSegmentApiVersionReader() );

Most people that version by URL segment don't want the API version parameter at all. You can achieve that by having the API Explorer extensions substitute in the API version automatically. For example:

services.AddApiVersioning( options => options.ApiVersionReader = new UrlSegmentApiVersionReader() )
        .AddApiExplorer( options => options.SubstituteApiVersionInUrl = true );

This would result in your example as having no API version parameter at all and the URL template would appear as: api/v2/schedule/{ean}.

[mhsimkin]

Thanks.

When I sent you the screen shot, I had already set the SubstitureApiVersionInUrl option on the call to AddApiExplorer.

While waiting for your response, I did some more digging, and was able to figure out I needed to explicitly set the ApiVersionReader to be just UrlSegmentApiVersionReader.

Once I did that, the OpenApi description was correct, but any request to the URL returned a 404.

I removed call to set the ApiVersionReader, but I still get a 404.

// 20221006140940
// http://localhost:10001/api/v2/schedule/9781524763169

{
  "type": "https://docs.api-versioning.org/problems#unspecified",
  "title": "Unspecified API version",
  "status": 400,
  "detail": "An API version is required, but was not specified.",
  "Code": "ApiVersionUnspecified",
  "traceId": "00-f301b875f681829f53fabed0d84fe32e-6f7e144ed2e9b698-00"
}

I'm missing something, the questions is what.

[commonsensesoftware]

That seems strange. What's the setup/signature of your controller?

[mhsimkin]

Thank you for all the help.

At some point between Thursday last week and today, I removed the apiVersion constraint from the RouteAttribute on the controller class.

It is time for me to step away from the computer as I'm making stupid mistakes, and wasting peoples time.

Thank you.

-marc

[commonsensesoftware]

Ah... no worries. Welcome to being human. Fortunately, we're not all 🤖🤖🤖 here. 😆

The route constraint is definitely necessary so that API Versioning knows how and where to extract value from. You are then free to construct route templates in any form you choose.

Glad you got things working.