Oh my God, Swagger API文档竟然可以这样写？

有态度的马甲

发布于 2020-12-18 11:31:30

5610

发布于 2020-12-18 11:31:30

文章被收录于专栏：精益码农

最好的总会在不经意间出现。

“作为后端程序员，免不了与前端同事对接API，一个书写良好的API设计文档可有效提高与前端对接的效率。

为避免联调时来回撕逼，今天我们聊一聊正确编写Swaager API文档的姿势。

基础Swagger用法

在ConfigureServices配置Swagger文档,在Configure启用中间件

 // Install-Package Swashbuckle.AspNetCore 略 
 services.AddSwaggerGen(
      options =>
      {
           options.SwaggerDoc("v1", new OpenApiInfo { Title = "EAP API", Version = "v1" });
      }
  );     
---

app.UseSwagger();
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "EAP API");
});

应用会在/Swagger页面加载最基础的API文档。

以一个最简单的Post请求为例，细数这最基础Swagger文档的弊病：

[HttpPost]
public async Task<bool> AddHotmapAsync([FromBody] CreateHotmapInput createHotmapInput)
{
     var model = ObjectMapper.Map<CreateHotmapInput, Hotmap>(createHotmapInput);
     model.ProfileId = CurrentUser.TenantId;
     return await _hotmaps.InsertAsync(model)!= null;
}

产生如图示SwaggerUI：

Post请求的Payload字段过于复杂，竟不给前端传值example？
没有约定请求的媒体类型，前端会不会给你另外一个surprise?
API 文档没有指示响应的媒体类型，前端以哪种姿势接收？
API文档没有指示响应的预期输出内容、状态码，前端会不会抓狂？

下文就来根治这些顽疾，书写一个自述性、优雅的API文档。

Swagger最佳实践

三下五除二，给出示例：

/// <summary>
/// 添加热力图
/// </summary>
/// <remarks>
/// Sample request:
/// ```
///  POST /hotmap
///  {
///      "displayName": "演示名称1",
///      "matchRule": 0,
///      "matchCondition": "https://www.cnblogs.com/JulianHuang/",
///      "targetUrl": "https://www.cnblogs.com/JulianHuang/",
///      "versions": [
///      {
///         "versionName": "ver2020",
///         "startDate": "2020-12-13T10:03:09",
///         "endDate": "2020-12-13T10:03:09",
///          "offlinePageUrl": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  //  没有绑定图片和离线网页的对应属性传 null
///          "pictureUrl": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
///          "createDate": "2020-12-13T10:03:09"
///      }
///    ]
///  }
///```
/// </remarks>
/// <param name="createHotmapInput"></param>
/// <returns></returns>
[Consumes("application/json")]
[Produces("text/plan")]
[ProducesResponseType(typeof(Boolean), 200)]
[HttpPost]
public async Task<bool> AddHotmapAsync([FromBody] CreateHotmapInput createHotmapInput)
{
     var model = ObjectMapper.Map<CreateHotmapInput, Hotmap>(createHotmapInput);
     model.ProfileId = CurrentUser.TenantId;
     return await _hotmaps.InsertAsync(model)!=null;
}

通过给API添加XML注释：remarks

“注意如果注释内容包含代码，可以使用Markdown的代码语法```,在注释里面优雅显示代码。

通过Consumes,Produces特性指示action接收和返回的数据类型，也就是媒体类型。

“Consumes、Produces是指示请求/响应支持的content-type的过滤器，位于Microsoft.AspNetCore.Mvc命名空间下。

通过ProducesResponseType特性指示API响应的预期内容、状态码

API文档显示如下：

这样的Swagger文档才正确表达了后端程序员的内心输出。

在Swagger文档上显示注释

生成XML文档文件在项目上[右键]-[属性]-[生成标签页]-[勾选XML文档文件]；或者直接在项目csproj文件--[PropertyGroup]添加 <GenerateDocumentationFile>true</GenerateDocumentationFile>
在AddSwaggerGen方法添加下行，启用注释文件

// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{this.GetType().Assembly.GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
opt.IncludeXmlComments(xmlPath);