如何动态实现api版本控制和swagger文档 [英] How to implement api versioning and swagger document dynamically

问题描述

我正在使用dotnet core api。我必须在api上实现版本控制。

I am working in dotnet core api. I have to implement versioning on api. and swagger document should be categorized by api version.

推荐答案

在.NetCore中，可以通过在nuget中添加以下引用来实现api版本控制/ p>

In .NetCore api versioning can be implement by adding below reference from nuget

1. Microsoft.AspNetCore.Mvc.Versioning


2. Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

添加引用后，请在项目的启动文件中执行以下操作。在AddMvc行之前添加下面的行。我将使用Header-api版本控制。这意味着客户端将在标题中提及版本。标头名称是可自定义的。

After adding reference do following in startup file of your project. Add below line before AddMvc line. I will use Header-api versioning. It means client will mention the version in header. Header name is customizable.

 services.AddApiVersioning(this.Configuration);

AddApiVersioning的定义就像（在不同的扩展类中）：

Definition of AddApiVersioning would be like as (In different extension class):

public static void AddApiVersioning(this IServiceCollection services, IConfiguration configuration)
{
    services.AddApiVersioning(apiVersioningOptions =>
    {
        apiVersioningOptions.ApiVersionReader = new HeaderApiVersionReader(new string[] { "api-version" }); // It means version will be define in header.and header name would be "api-version".
        apiVersioningOptions.AssumeDefaultVersionWhenUnspecified = true;
        var apiVersion = new Version(Convert.ToString(configuration["DefaultApiVersion"]));
        apiVersioningOptions.DefaultApiVersion = new ApiVersion(apiVersion.Major, apiVersion.Minor);
        apiVersioningOptions.ReportApiVersions = true;
        apiVersioningOptions.UseApiBehavior = true; // It means include only api controller not mvc controller.
        apiVersioningOptions.Conventions.Controller<AppController>().HasApiVersion(apiVersioningOptions.DefaultApiVersion);
        apiVersioningOptions.Conventions.Controller<UserController>().HasApiVersion(apiVersioningOptions.DefaultApiVersion);               
        apiVersioningOptions.ApiVersionSelector = new CurrentImplementationApiVersionSelector(apiVersioningOptions);
    });
    services.AddVersionedApiExplorer(); // It will be used to explorer api versioning and add custom text box in swagger to take version number.
}

此处的配置[ DefaultApiVersion]是值1.0的appsetting中的关键b $ b如上面的代码所示，我们已使用Convention为每个控制器定义api版本。如果只有一个api版本，并且您不想使用[ApiVersion]属性标记每个控制器，则该功能很有用。

Here configuration["DefaultApiVersion"] is a key in appsetting having value 1.0 As in above code we have used Convention to define api version for each controller. It is useful when there is one api version and you don't want to label each controller with [ApiVersion] attribute.

如果您不想使用Convention定义控制器的版本。使用属性标签定义版本。如下所示：

If you don't want to use the Convention menthod to define version of controller. use attribute label to define version. like as below:

[Route("[controller]")]
[ApiController]
[ApiVersion("1.0")]
public class TenantController : ConfigController

完成此操作后，启动文件并添加以下代码。

Once this done go to StartUp file and add below code.

 app.UseApiVersioning(); //Here app is IApplicationBuilder

这是api版本控制的完整解决方案。

That is complete solution for api versioning.

要摇摇欲坠，我们必须添加如下定义的nuget包：

1. Swashbuckle.AspNetCore


2. Swashbuckle.AspNetCore.SwaggerGen


3. Swashbuckle.AspNetCore.SwaggerUI
   添加引用后，请执行以下操作：在Services.UseApiVersioning（）

services.AddSwaggerGenerationUI（）;

services.AddSwaggerGenerationUI();

AddSwaggerGenerationUI的定义如下：

The definition of AddSwaggerGenerationUI is below in extens :

public static void AddSwaggerGenerationUI(this IServiceCollection services)
{
    var provider = services.BuildServiceProvider()
                     .GetRequiredService<IApiVersionDescriptionProvider>();
    services.AddSwaggerGen(action =>
    {                
        action.OrderActionsBy(orderBy => orderBy.HttpMethod);
        action.UseReferencedDefinitionsForEnums();
        foreach (var item in provider.ApiVersionDescriptions)
        {
            action.SwaggerDoc(item.GroupName, new Swashbuckle.AspNetCore.Swagger.Info
            {
                Title = "Version-" + item.GroupName,
                Version = item.ApiVersion.MajorVersion.ToString() + "." + item.ApiVersion.MinorVersion
            });
        }
    });
}

此代码将在管线中大张旗鼓。现在我们必须使用招摇。在启动文件中执行以下代码。

This code will add swagger in pipeline. Now we have to use swagger. do below code in startup file.:

app.UseSwaggerGenerationUI(this.Configuration)

UseSwaggerGenerationUI的定义如下：

Definition of UseSwaggerGenerationUI would be like as :

public static void UseSwaggerGenerationUI(this IApplicationBuilder applicationBuilder, IApiVersionDescriptionProvider apiVersionDescriptionProvider, IConfiguration configuration)
{
    applicationBuilder.UseSwagger(c =>
    {
        c.RouteTemplate = "/api/help/versions/{documentname}/document.json";

        c.PreSerializeFilters.Add((swaggerDoc, httpReq) => swaggerDoc.BasePath = "/api");
    });

    applicationBuilder.UseSwaggerUI(c =>
    {
        c.RoutePrefix = "api/help";
        c.DocumentTitle = "Api Help";
        foreach (var item in apiVersionDescriptionProvider.ApiVersionDescriptions)
        {
            c.SwaggerEndpoint($"/api/help/versions/{item.GroupName}/document.json", item.GroupName);
        }
    });
}

这篇关于如何动态实现api版本控制和swagger文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！