关于swagger:手把手教你AspNetCore-WebApiSwaggerApi文档

前言

小明曾经实现“待办事项”的增删改查，并美滋滋向负责前端的小红介绍 Api 接口，小红很忙，临时没有工夫听小明介绍，心愿小明能给个 Api 文档。对于码农小明来说能不写文档就尽量不要写，不过这也难不倒小明，他晓得 Swagger 不仅能够主动生成 Api 文档，并还能够用 Swagger 进行接口测试。

Swagger 是什么？

Swagger 用于形容 REST API。它容许计算机和人员理解服务的性能，而无需间接拜访实现（源代码、网络拜访、文档）。

包装置

• 右键单击“解决方案资源管理器”>“治理 NuGet 包”中的我的项目
• 将“包源”设置为“nuget.org”
• 确保启用“包含预发行版”选项
• 在搜寻框中输出“Swashbuckle.AspNetCore”
• 从“浏览”选项卡中抉择最新的“Swashbuckle.AspNetCore”包，而后单击“装置”

增加 Swagger 生成器

将 Swagger 生成器增加到 Startup.ConfigureServices 办法中的服务汇合中：

services.AddSwaggerGen();

配置 Swagger 中间件

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

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

XML 正文

• 在“解决方案资源管理器”中右键单击该我的项目，而后抉择“编辑 <project_name>.csproj”。
• 手动将 PropertyGroup 增加：

<GenerateDocumentationFile>true</GenerateDocumentationFile>

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

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

成果

小结

目前为止，小明终于把 API 文档也搞定了，摸了摸润滑的脑袋，小明美滋滋把 API 地址给小红发去，心想这样小红必定很称心了吧，但对不能与小红面对面的交换接口也有一丝丝淡淡的悲观。