开发环境

VisualStudio 2019 16.8.3

ASP.NET Core 5.0

正文

1.前言

现在是2021年初，现如今的微服务、前后端分离相信已经无人不知，而WebAPI也是重要的技术栈。

说到API那肯定离不开接口文档，而Swagger正是我们生成接口文档的利器，在ASP.NET Core 5.0，通过VS生成的WebAPI项目模板中已经自动引入了Swashbuckle.AspNetCore包，生成的Startup.cs中也自带Swagger文档的配置，大概是这个样子：

默认为我们的每个API生成了接口文档。

2.Swagger生成多个版本的接口文档

随着时间和技术的更替，我们的API也会升级，在增加功能或者修改规范时可能导致旧版API不能正常使用，所以我们需要在一个独立的新版API上进行升级修改，旧的API仍然保留。这时候就诞生了多个版本的API，那么如何在Swagger中添加多个版本的文档呢？

①在ConfigureServices中定义其他版本的SwaggerDoc：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "LeoAdmin.API", Version = "v1" });
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "LeoAdmin.API", Version = "v2" });
});

②在SwaggerUI中添加其他版本文档的url：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "LeoAdmin.API v1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "LeoAdmin.API v2");
});

这样我们就生成了两个版本的接口文档（v1、v2）：

3.为API进行版本分组

①使用特性为API进行分组：

[HttpGet]
[ApiExplorerSettings(GroupName = "v1")]
public IEnumerable<WeatherForecast> Get()

在Action方法上声明特性ApiExplorerSettings，然后GroupName="v1"指定SwaggerDoc名称v1，使当前这个Action放在v1这个文档下。

PS：也可以将该特性标记在Controller，使整个Controller下的Action都属于该指定文档。

②按约定对API进行分组：

将不同版本API的Controllor放在单独的文件夹，这时候创建的控制器默认命名空间的末尾就会包含文件夹得名称：

创建一个API分组名约定的类，继承自IControllerModelConvention， 根据命名空间来进行版本分组：

public class ApiExplorerGroupPerVersionConvention : IControllerModelConvention
{
    public void Apply(ControllerModel controller)
    {
        var controllerNamespace = controller.ControllerType.Namespace; // e.g. "XXX.XX.Controllers.V1"
        var apiVersion = controllerNamespace.Split('.').Last().ToLower();

        controller.ApiExplorer.GroupName = apiVersion;
    }
}

在services.AddControllers中，配置约定：

services.AddControllers(c => { c.Conventions.Add(new ApiExplorerGroupPerVersionConvention()); });

这时候就完成了对每个Controller进行了版本分组，V1文件夹下的Controller放在v1文档下，V2文件夹下的Controller放在v2文档下。

PS：根据命名空间约定只是一种方法，也可以根据控制器上其他属性或特性来进行约定分组。

4.高级应用

未完待续......

感谢阅读，敬请斧正。