ASPNetCore自动生成swagger API文档

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