手把手教你ASP.NET Core：Web API文档利器Swagger

Swagger是什么？

本质上就是使用 OpenAPI 3.0 规范写一份文档，该文档描述了 API 的各类状态，你能够拿着这份文档部署在 Swagger-UI 上给对接的同事查看，也能够在 SoapUI 等工具中进行测试。

添加并配置 Swagger 中间件

须要先安装“Swashbuckle.AspNetCore”包，将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中：

services.AddSwaggerGen();

在 Startup.Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务：

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

XML 注释

• 在“解决方案资源管理器”中右键单击该项目，而后选择“编辑<project_name>.csproj” 。

• 手动将PropertyGroup添加：

  true

更改services.AddSwaggerGen();代码以下：

services.AddSwaggerGen((c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
}));

演示效果

小结

如今咱们终于把API文档也搞定了，不再用傻傻的经过Word手工写API文档给前端了，而也不怕咱们更新了API而文档没有同步更新。