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

系列导航及源代码

使用.NET 6开发TodoList应用文章索引

需求

在日常开发中，我们需要给前端提供文档化的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版本选择，以及授权控制都在界面上有所显示。

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

一点扩展

导入API客户端

右击swagger界面上的json文件链接选择另存为，再去对应的API客户端导入json文件即可。

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

生成fake服务端

可以去这里：Swagger Editor，上传swagger json文件，选择生成服务端或者客户端。

为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文档现在已经有接口说明了：

总结

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

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

参考资料