如何在ASP.NET Core(ABP)项目中生成自定义的Swagger文档

后端开发人员提供一个书写良好的Swagger文档页面可有效提高与前端对接的效率

---

安装Nuget包

对core项目安装Swashbuckle.AspNetCore

然后在Startup.cs中的ConfigureServices方法增加配置

services.AddMvc();

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

以及Configure方法中

app.UseSwagger();

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

书写XML注释

微软官方文档上一个较为完整的例子

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
// [Obsolete]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

在swagger文档上显示注释

1. 在【解决方案管理器】右击Application项目，选择属性
2. 在【生成】页面，勾选XML文档文件
3. 在【取消显示警告】一栏中增加1591;

配置Swagger参数(4.0.0)

1. 打开Startup.cs,在ConfigureServices方法中增加下行

   options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "<XML File Path>"));

2. 在Configure方法中自定义Swagger页面样式

   options.ShowExtensions();
   options.EnableValidator();
   // 将选择的接口地址连接到URL，方便与他人定位
   options.EnableDeepLinking();
   // 启用过滤器（大小写敏感）
   options.EnableFilter();
   // 展开级别
   options.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None);
   // 右侧显示方法名
   options.DisplayOperationId();
   
   /* 启用下面代码，生成适合用于对接的Swagger页面 */
   
   // 默认显示model
   options.DefaultModelRendering(Swashbuckle.AspNetCore.SwaggerUI.ModelRendering.Model);
   // 模型展开到2级
   options.DefaultModelExpandDepth(2);
   // 隐藏model列表
   options.DefaultModelsExpandDepth(-1);
   // 隐藏 [Try it]
   options.SupportedSubmitMethods();

增加折叠块注释

新增一个过滤器

public class TagDescriptionsDocumentFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Tags = new[]
        {
            new Tag { Name = "Admin", Description = "管理员" },
            new Tag { Name = "User", Description = "用户" }
        };
    }
}

然后在Startup.cs > ConfigureServices > AddSwaggerGen里添加

options.DocumentFilter<TagDescriptionsDocumentFilter>();

---

参考

Swagger UI Integration - ASP.NET Boilerplate

Get started with Swashbuckle and ASP.NET Core | Microsoft Docs

Swashbuckle.AspNetCore On GitHub