api - 如何动态实现api版本控制和swagger文档

Question

我正在使用 dotnet core api。我必须在 api 上实现版本控制。 swagger文档应该按照api版本进行分类。

Answer 1

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

1. Microsoft.AspNetCore.Mvc.Versioning
2. Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

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

 services.AddApiVersioning(this.Configuration);

AddApiVersioning 的定义如下(在不同的扩展类中):

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”]是appsetting中的一个键，值为1.0 如上面的代码所示，我们使用 Convention 来定义每个 Controller 的 api 版本。当只有一个 api 版本并且您不想用 [ApiVersion] 属性标记每个 Controller 时，它非常有用。

如果您不想使用约定方法来定义 Controller 的版本。使用属性标签来定义版本。如下所示:

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

完成后，转到启动文件并添加以下代码。

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

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

对于 swagger，我们必须添加 nuget 包，定义如下:

1. Swashbuckle.AspNetCore
2. Swashbuckle.AspNetCore.SwaggerGen
3. Swashbuckle.AspNetCore.SwaggerUI 添加引用后，执行以下操作:在 Services.UseApiVersioning() 之后添加以下行

services.AddSwaggerGenerationUI();

AddSwaggerGenerationUI 的定义扩展如下:

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
            });
        }
    });
}

此代码将在管道中添加 swagger。现在我们必须使用 swagger。在启动文件中执行以下代码:

app.UseSwaggerGenerationUI(this.Configuration)

UseSwaggerGenerationUI 的定义如下:

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);
        }
    });
}