现在是2021年初,现如今的微服务、前后端分离相信已经无人不知,而WebAPI也是重要的技术栈。
说到API那肯定离不开接口文档,而Swagger正是我们生成接口文档的利器,在ASP.NET Core 5.0,通过VS生成的WebAPI项目模板中已经自动引入了Swashbuckle.AspNetCore包,生成的Startup.cs中也自带Swagger文档的配置,大概是这个样子:
默认为我们的每个API生成了接口文档。
随着时间和技术的更替,我们的API也会升级,在增加功能或者修改规范时可能导致旧版API不能正常使用,所以我们需要在一个独立的新版API上进行升级修改,旧的API仍然保留。这时候就诞生了多个版本的API,那么如何在Swagger中添加多个版本的文档呢?
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "LeoAdmin.API", Version = "v1" });
c.SwaggerDoc("v2", new OpenApiInfo { Title = "LeoAdmin.API", Version = "v2" });
});
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "LeoAdmin.API v1");
c.SwaggerEndpoint("/swagger/v2/swagger.json", "LeoAdmin.API v2");
});
这样我们就生成了两个版本的接口文档(v1、v2):
[HttpGet]
[ApiExplorerSettings(GroupName = "v1")]
public IEnumerable<WeatherForecast> Get()
在Action方法上声明特性ApiExplorerSettings,然后GroupName="v1"指定SwaggerDoc名称v1,使当前这个Action放在v1这个文档下。
PS:也可以将该特性标记在Controller,使整个Controller下的Action都属于该指定文档。
将不同版本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:根据命名空间约定只是一种方法,也可以根据控制器上其他属性或特性来进行约定分组。
未完待续......
感谢阅读,敬请斧正。
版权声明:本文由不落阁原创出品,转载请注明出处!
广告位
跟不落阁,学DOTNET!
广告位
那个接口地址中的v1、v2是怎么设置的?
2021-08-30 17:26回复