Swagger是一个应用很广的API文档框架。我们可以利用Swashbuckle.AspNetCore来实现NetCore Web API的自动接口文档，并以一个web ui的方式查看swagger样式的API接口文档及调试。
通常我们用NetCore编写Web API给前端开发者、手机App或其它服务调用，通过这种自动生成的API文档能实时反应接口的变化，避免自己编写的API文档和代码没有保持一致的问题。
步骤很简单：
1. 添加Swashbuckle.AspNetCore库，通过Nuget搜索添加
<PackageReference Include="Swashbuckle.AspNetCore" Version="2.4.0" />
2. 注入Swagger API描述json的生成服务
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}
3. App添加使用Swagger和ui展示
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
}
这里注意Endpoint值可以是相对值也可以是绝对值，如果是相对值，"/swagger/v1/swagger.json"是缺省值，比如你的服务部署在http://www.xxx.com/test下，则这个值得改为"/test/swagger/v1/swagger.json"
这样就可以了，在浏览器里输入地址加/swagger就可以看到swagger样式的API文档了。
image.png
再进一步，我们把中文注释什么的也加到API文档里，比如
/// <summary>
/// Get请求注释
/// </summary>
/// <returns></returns>
// GET api/values
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
只需2个步骤：
1. 编译的时候生成xml文档文件
点击项目 右键 属性 在生成tab页里输出里勾选XML文档文件
image.png
2. 在注入swagger服务时添加代码
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
var basePath = Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = System.IO.Path.Combine(basePath, "do.xml");
c.IncludeXmlComments(xmlPath);
});
注意参数里的xml文件名必须和第一步里设置的xml文件名一致。
其实就是让swagger生成json时去读取生成的xml文档，然后组合在一起。
最后我们再看看效果：
image.png
