Using single swagger documentation for different Version of Web Controllers

[Boriszn]

Hi.
Quite nice and useful solution.

Would it be possible to configurate versioning with swagger to use different API versions But withing one swagger documentation (Open Api specification) ?

[commonsensesoftware]

Can you elaborate a little on exactly what you mean?

This project doesn't specifically care about or have an specific dependency on Swagger nor any specific implementation libraries such as Swashbuckle or NSwag. What's provided is an API Explorer library that is API version-aware. The API Explorer collates all actions by API version for you. Exactly how that information is used is purely up to you or the consuming library.

The examples provided use Swashbuckle, but that's purely for illustration purposes. If the information isn't collated the way you want, I'd consider alternate arrangements.

[Boriszn]

Thank you a lot for the feedback.

Sure, will explain in details then:

1. We configured to use Versioning as header based, so it adds version parameter to all Api calls, like on on configuration below:

services.AddApiVersioning(o => {
	o.ReportApiVersions = true;
	o.AssumeDefaultVersionWhenUnspecified = true;
	o.DefaultApiVersion = new ApiVersion(1, 0);
 
	o.Conventions.Controller<HomeV1Controller>().HasApiVersion(new ApiVersion(1, 0));
	o.Conventions.Controller<HomeV2Controller>().HasApiVersion(new ApiVersion(2, 0));
});

As understood it will use version parameter to route to the proper method/controller, Right ?
(For example: if passed version 1.0 it will lead to method which marked for version 1.0 etc..)

2. For the Swagger configuration below will generate swagger documentations (OpenApi specs) for all versions, Right ?

app.UseSwaggerUI(
        options =>
        {
            foreach ( var description in provider.ApiVersionDescriptions )
            {
                options.SwaggerEndpoint(
                    $"/swagger/{description.GroupName}/swagger.json",
                    description.GroupName.ToUpperInvariant() );
            }
        } );

If Yes, then main question: How to use this version parameter alongside with swagger withing one API endpoint (or Swag. API spec)?

Is it clear or should I add more details ?

Thanks,
Boris
P.S
And yes It may be a question to Swagger also.

[commonsensesoftware]

After AddApiVersioning you need this:

services.AddSwaggerGen(
    options =>
    {
        // note: need a temporary service provider here because one has not been created yet
        var provider = services.BuildServiceProvider()
                               .GetRequiredService<IApiVersionDescriptionProvider>();

        // add a swagger document for each discovered API version
        foreach ( var description in provider.ApiVersionDescriptions )
        {
            options.SwaggerDoc( description.GroupName, CreateInfoForApiVersion( description ) );
        }
    } );

This will produce a Swagger document per API version. Each Swagger document will be accessible as:

• /swagger/v1/swagger.json
• /swagger/v2/swagger.json
• ...

To see all the pieces together, please review the Startup.cs in the Swagger example. My understanding of the Swagger specification is that you cannot combine everything in a single document because the relative path for each URL must be unique. At least in Swashbuckle, the Swagger UI is setup for one document per API version. Diverging from that approach is certainly possible, but will likely require work on your side.

Also, if you're using the header method, then you need to configure that in the options. Only the query string or URL method work with the default configuration.

services.AddApiVerisoning(
    options =>
    {
        // specify the header[s] containing the api versions
        options.ApiVersionReader = new HeaderApiVersionReader( "api-version" );
     }
);

I hope that helps.

[commonsensesoftware]

Did this get you what you needed or are you still stuck?

[Boriszn]

@commonsensesoftware Thank you a lot for the feedback. Yeah, a bit stuck. Basically, my goal is combine somehow versioning with only one, single SwaggerDoc. Exactly like in issue mentioned Here
So, for example methods with V1 and methods with V2 should be listed in one Swagger Documentation.

[commonsensesoftware]

I don't profess to be a Swagger expert, but my understanding is that what you are asking may not be possible. By spec, Swagger requires all API URLs to be unique. If you're versioning by URL segment, you might be able to make this work by declarating a single Swagger document will all discovered APIs and their versions. You could call it "All" or something.

As circularly referenced in the link you provided, there is a new option in the API Explorer configuration that will automatically substitute the API version in URLs for you using:

services.AddMvcCore().AddVersionedApiExplorer(options => options.SubstituteApiVersionInUrl = true);

With the API version in the path, that should make it possible to have a single Swagger document. In addition, you don't need or want any of the logic to build multiple Swagger documents or use grouping. I've never tried this myself nor had anyone ask about it. I'm not sure exactly what Swashbuckle or NSwag will do. Grouping is a first-class concept in ASP.NET Core. You might have to subclass or change the API Explorer behavior to generate a flat list in the form that you want. The simplest way is to just create an another IApiDescriptionProvider that runs at the end and reorders the results. That's basically all the VersionedApiExplorer.cs does.

I hope that puts you on the right path.

[Boriszn]

Hi @commonsensesoftware.
Thank you a lot for the answer. I think your right.

However I found a way how yo do versioning with a parameters within one swagger doc:

1. Separate controllers to different name space, like ControllersV1.ControllerName, ControllersV2.ControllerName (exactly like in your Demo examples )
2. Add only one Swagger endpoint like: c.SwaggerEndpoint("/swagger/0.1/swagger.json", "API v0.1");
   So don't need this code:

        foreach ( var description in provider.ApiVersionDescriptions )
        {
            options.SwaggerDoc( description.GroupName, CreateInfoForApiVersion( description ) );
        }

3. And run :) You will have only one method name with version parameter which will be used for routing to proper controller/method. (So passing 1.0 will lead to methods in ControllersV1.ControllerName) etc)

But I like your solution more, will give it a try. (Because my looks a bit dirty)
Nevertheless, thank you a lot and I think this issue can be closed. :-)

[commonsensesoftware]

Great! Feel free to come back if you remain stuck. Thanks.

[mehdiAbbaspour]

hi ,
i using asp mvc 5 and api in area difrrent project ,
how to config mulitiapiVersion in swagger

[commonsensesoftware]

I don't believe there's anything special you need to do if you're mixing UI and APIs together in the same project, even if you're using Areas. To enable Swagger you need the API Explorer package and choose a supported Swagger generator such as Swashbuckle or NSwag. The sample project shows an end-to-end configuration using Swashbuckle.

If you're trying to use nested applications (which is not quite the same as Areas), you might want to peek at #391.

I hope that helps.