ASP.NET WebApi 使用Swagger生成接口文档

前言

公司一直采用Word文档方式与客户端进行交流。随着时间的推移，接口变的越来越多，文档变得也很繁重。而且一份文档经常由多个开发人员维护，很难保证文档的完整性。而且有时写完代码也忘了去更新文档，为了这些小事经常受客户端同事鄙视。

于是带着问题去查找解决方案，在网上一通乱搜后查找出以下两个工具：AspNet.WebApi.HelpPage，Swagger。

细细比较最终选择 Swagger ，因为优点实在太多，具体可网上自行搜索，在这里就不在赘述。

实现

1.引用NuGet包

2.设置项目属性，勾选生成XML注释文件

3.修改SwaggerConfig文件

　　3.1添加读取XML注释文件方法

 protected static string GetXmlCommentsPath(string name)
        {
            return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
        }

　　3.2修改SwaggerConfig配置

//设置接口描述xml路径地址
 c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));

4.效果展示

项目启动后，在域名后输入Swagger即可。如:http://localhost:65199/swagger/就会出现如下界面

点击试一下可在线调试接口。

5.注释详解

注释标签不同，UI呈现位置也不一样。常见的有<summary>、<remarks>、<response>

如果响应是一个对象或对象列表，可在当前项目下创建一个ViewModel，并将ViewModel添加到方法头部。如：

[ResponseType(typeof(ViewModel))]

UI效果：

总结

Swagger给我带来的两大好处是：1.以后再也不用写Word文档了，2.增加了写注释的好习惯