.NET Core使用swagger进行API接口文档管理

Swagger加入到.NET Core中跑起来之后会看到一个界面相对完善，体验比较好的接口文档样子的页面。这样我们在开发完接口后，不用花太多时间去维护一个接口文档提供给客户端。Swagger 可以从不同的代码中根据注释，生成 API信息。Swagger中的try it out！也可以触发调用接口。
下面记录一下整个.NET Core应用Swagger的过程

1.解决方案下创建 .NET Core 2.0 项目.NET Core中使用首先要用nuget引用Swashbuckle.AspNetCore，在startup.cs中加入如下代码

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
//Swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Hello", Version = "v1" });
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "WebApplication1.xml");
c.IncludeXmlComments(xmlPath);
});
services.AddMvcCore().AddApiExplorer();
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.UseMvc();
//Swagger
app.UseMvcWithDefaultRoute();
app.UseSwagger(c =>
{
});
app.UseSwaggerUI(c =>
{
c.ShowExtensions();
c.ValidatorUrl(null);
c.SwaggerEndpoint("/swagger/v1/swagger.json", "test V1");
});
}
注意：引用的是Swashbuckle.AspNetCore 不是Swashbuckle

2.修改Controller中对应的注释

// GET api/values/5
/// <summary>
/// 获取方法
/// </summary>
/// <param name="id">唯一id</param>
/// <returns></returns>
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}

3.接下来我们还需要在项目的属性中，选择生成中勾上XML生成文档。如图：

然后跑起来就是了：）
浏览器url: localhost:0000/swagger
try it out
execute

4.针对某些项目里面一些参数不是放在body里面而是固定放在hearder中的。比如说appid或者token

public class AddAuthTokenHeaderParameter : IOperationFilter
{

public void Apply(Operation operation, OperationFilterContext context)
{

if (operation.Parameters == null)
{
operation.Parameters = new List<IParameter>();
}
operation.Parameters.Add(new NonBodyParameter()
{
Name = "token",
In = "header",
Type = "string",
Description = "token认证信息",
Required = true
});
operation.Parameters.Add(new NonBodyParameter()
{
Name = "appid",
In = "header",
Type = "string",
Description = "appid",
Required = true
});
}
我们在ConfigureServices添加了OperationFilter()，通过这种方式我们可以在swagger中显示header的token和appid，AddAuthTokenHeaderParameter 的apply的属性context中带了controller以及action的各种信息，可以配合实际情况使用

要注意的是，swagger中的控制器中除了需要发布出去的方法（带有http方法属性的）是public公有方法外，其他方法最好都用private私有方法，swagger低版本的编译生成可能会将所有的public方法都解析进去，而非控制器方法就会导致样式错乱。

项目可以结合swagger+yapi进行API的管理方式，除此之外DOClever（开源）也是一个不错的API管理工具（还没有了解过），关于两个管理工具有机会跟大家分享。