首页 学海无涯 WebAPI .NET Core WebAPI 使用Swagger实现API多版本控制
.NET Core WebAPI 使用Swagger实现API多版本控制
摘要 在.NET WebAPI中通过Swagger生成多个文档,实现API版本控制。

开发环境

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.高级应用

未完待续......

感谢阅读,敬请斧正。


版权声明:本文由不落阁原创出品,转载请注明出处!

本文链接:http://www.leo96.com/article/detail/54

广告位

来说两句吧
最新评论

暂无评论,大侠不妨来一发?