swagger for c# webapi

最近迷上了前后端分离的开发架构，工作中的项目几乎都采取这种模式，自己主要担任服务端RestFul风格的Webapi开发。那么问题来了，当前端开发人员找我要api说明文档的时候，曾一度非常可耻的冒出过word、excel之类的想法,oh my god！我一定是昨晚吃的东西还没消化，吃撑了。好了，言归正传，在团队开发中，一个好的 API 文档可以减少很多 交流成本 ，也可以使一个新人快速上手业务。so，swagger就是一个非常不错的选择，而且现在nuget中可以安装swagger的.net支撑包，这就更加便捷了，完全可以将开发人员从api文档的编写工作中解放出来。

具体的操作方式如下：

1、新建一个webapi 2项目，这里就不再赘述了

2、使用程序包管理器控制台安装Swashbuckle，命令如下：Install-Package Swashbuckle

3、安装好以后，会自动在项目的App_Start文件夹下新建一个SwaggerConfig.cs文件

4、打开项目的属性配置窗口，在生成选项卡中勾选XML文档文件，并配置文档路径及名称为bin\Swagger.xml（具体名字可随个人喜好或者项目的统一规范标准进行命名）

至此就已经OK了，调试运行模式/发布到iis后，在http://baseurl/swagger/ 下即可看到所有controll及其下所有的api

展开Account后的界面

但是，问题来了，我的api为什么都没有说明性的文字呢？我在代码中明明是增加了方法注释的呀

好吧，不用着急，做几步简单的处理即可解决这个问题

1、在SwaggerConfig.cs中，打开Register方法里的c.IncludeXmlComments(GetXmlCommentsPath());这句代码

2、新增GetXmlCommentsPath方法

private static string GetXmlCommentsPath()
{
　　return System.String.Format(@"{0}\bin\swagger.XML", System.AppDomain.CurrentDomain.BaseDirectory);
}

注意，上面代码中的文档路径要跟项目属性中配置的一样，包括名称和路径地址，我之前配置的时候就只写了Swagger.XML，忘记了bin\目录

好了，再次调试运行/发布到iis（已经发布到IIS的直接编译一下即可），大功告成。

swagger非常棒的一个特性，就是可以直接测试

 

 在Value中输入参数，点击Try it out!，即可看到api的返回结果

怎么样，很棒吧！