欢迎光临
我的个人博客网站

使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化


系列导航及源代码

需求

在日常开发中,我们需要给前端提供文档化的API接口定义,甚至需要模拟架设一个fake服务用来调试接口字段。或者对于后端开发人员来说,我们可以通过导入这个接口定义文件到Postman或者其他API客户端,省去我们手动录入的麻烦。所以本文就实现如何使用Swagger来管理API接口文档化。

但是在本文中,我们不涉及关于NSwag的相关内容,通过NSwag,我们甚至可以直接生成前端可以使用的接口定义。关于NSwag的使用方法,请参考:NSwag 和 ASP.NET Core 入门以及官方文档RicoSuter/NSwag

目标

实现TodoList项目的接口文档化。

原理与思路

在使用IDE或者cli生成新的Web API项目的时候,项目模版里已经自带了Swashbuckle.AspNetCore包用来生成swagger文档,我们需要使用这个包来实现相关功能。

实现

实现基础的Swagger API文档

Program中极有可能已经添加了SwaggerGen服务了,我们可以做一点小修改,因为之前我们写过两个版本的TodoItemController,希望将两个版本也反映到swagger文档中:

// 省略其他... builder.Services.AddSwaggerGen(s => {     s.SwaggerDoc("1.0", new OpenApiInfo { Title = "TodoList API", Version = "1.0"});     s.SwaggerDoc("2.0", new OpenApiInfo { Title = "TodoList API", Version = "2.0"}); }); 

中间件的引入我们也可以修改一下:

if (app.Environment.IsDevelopment()) {     app.UseSwagger();     app.UseSwaggerUI(s =>     {         s.SwaggerEndpoint("/swagger/1.0/swagger.json", "TodoList API v1.0");         s.SwaggerEndpoint("/swagger/2.0/swagger.json", "TodoList API v2.0");     }); } 

如果在API接口版本控制的那一章我们不是使用的通过更改URL的方式实现的API多版本,那么现在只需要对应版本的Controller上添加:

  • TodoItemController.cs
[Route("/todo-item")] [ApiExplorerSettings(GroupName = "1.0")] [ApiController] public class TodoItemController : ControllerBase // 省略其他... 

以及

  • TodoItemV2Controller.cs
[Route("/todo-item")] [ApiExplorerSettings(GroupName = "2.0")] [ApiController] public class TodoItemV2Controller : ControllerBase // 省略其他... 

如果是使用URL路径实现不同版本API的文档,可以参考这篇文章的实现:ASP.NET Core 3.1 WebApi Swagger与API版本控制的美妙结合

为Swagger添加认证授权功能

为了添加授权支持,我们可以修改Swagger服务选项如下,增加授权配置:

  • Program.cs
// 省略其他 s.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme {     In = ParameterLocation.Header,     Description = "Add JWT with Bearer",     Name = "Authorization",     Type = SecuritySchemeType.ApiKey,     Scheme = "Bearer" });  s.AddSecurityRequirement(new OpenApiSecurityRequirement {     {         new OpenApiSecurityScheme         {             Reference = new OpenApiReference             {                 Type = ReferenceType.SecurityScheme,                 Id = "Bearer"             },             Name = "Bearer",         },         new List<string>()     } }); 

验证

启动Api项目,打开swagger地址,可以看到API版本选择,以及授权控制都在界面上有所显示。
使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化

具体的切换查看我就不贴截图了,大家可以自己试一试。

一点扩展

导入API客户端

右击swagger界面上的json文件链接选择另存为,再去对应的API客户端导入json文件即可。
使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化

使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化

Postman在这方面做的比较好的是它能够按照json文件内接口的结构关系生成对应的文件夹结构。

生成fake服务端

可以去这里:Swagger Editor,上传swagger json文件,选择生成服务端或者客户端。
使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化

为swagger生成完整的数据定义及API注释文档

需要开启XML注释功能,为此我们同时需要禁止1591warning(为了避免对所有的方法、类、字段发出没有xml注释文档的警告)。修改项目设置如下:

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">   <DocumentationFile>TodoList.Api.xml</DocumentationFile>   <OutputPath></OutputPath>   <NoWarn>1701;1702;1591</NoWarn> </PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">   <NoWarn>1701;1702;1591</NoWarn> </PropertyGroup> 

修改SwaggerGen注入的配置:

  • TodoList.Api.csproj
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); s.IncludeXmlComments(xmlPath); 

我们以CreateTodoList接口为例去添加xml注释,

  • TodoListController.cs
/// <summary> /// 创建新的TodoList,只有Administrator角色的用户有此权限 /// </summary> /// <param name="command">创建TodoList命令</param> /// <returns></returns> [HttpPost] [Authorize(Policy = "OnlyAdmin")] [ServiceFilter(typeof(LogFilterAttribute))] public async Task<ApiResponse<Domain.Entities.TodoList>> Create([FromBody] CreateTodoListCommand command) {     return ApiResponse<Domain.Entities.TodoList>.Success(await _mediator.Send(command)); } 

再打开swagger文档查看,可以看到swagger文档现在已经有接口说明了:
使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化

总结

在本文中我们实现了swagger文档的生成和一些配置选项的作用,如果需要用到更多OpenAPI相关的特性,推荐熟悉一下NSwag这个组件,它提供了更加强大的功能。

下一篇文章我们实现程序的健康检查功能。

参考资料

  1. NSwag 和 ASP.NET Core 入门
  2. RicoSuter/NSwag
  3. ASP.NET Core 3.1 WebApi Swagger与API版本控制的美妙结合
赞(0) 打赏
未经允许不得转载:张拓的天空 » 使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化
分享到: 更多 (0)

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

专业的IT技术经验分享 更专业 更方便

联系我们本站主机

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

微信扫一扫打赏