使用swagger实现web api在线接口文档

1、前言

　　一般咱们的项目会包含许多对外的接口，这些接口都须要文档化，标准的接口描述文档须要描述接口的地址、参数、返回值、备注等等；像咱们之前的作法是写在word/excel，一般是按模块划分，例如一个模块包含n个接口，就造成一个文档，而后再用版本控制管理。这样作的缺点是：

1.不够直观，每次打开文档查看接口很麻烦

2.文档的维护难度大

3.调用方和测试人员使用麻烦，须要先去找接口，在用相应的工具测试（例如使用浏览器还可能要安装插件）

　　咱们但愿是能够直接在线浏览，而后直接用浏览器测试。而接口的详细描述都在程序里用注释完成。swagger就能够完成这个工做（ps好像不少开发人员都还不知道这个东西。。。）。

2、使用Swagger

　　Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

　　在web api 使用swagger能够说很是简单，不须要编写任何代码，彻底依赖于插件。具体步骤以下：

　   1.新建一个web api项目

　　

　　2.使用nuget添加Swashbuckle包

　　

　　3.完成

　　没错，就是这么简单！运行项目，转到地址 http://localhost:57700/swagger/ui/index 会看到以下页面，这是默认添加的两个apicontroller：　　

　　这个时候接口尚未具体的描述信息等，例如咱们给ValuesController.Get添加注释描述，在页面上仍是没有显示出来。须要按照以下步骤实现：

　　1. 在app_start 下 SwaggerConfig 大100行的位置找到 //c.IncludeXmlComments(GetXmlCommentsPath()); 以下注释，改成：c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name)); （注意去掉注释了）

　　2. 在SwaggerConfig添加一个方法代码：

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

　　3. 修改项目生成，在bin下对应的xml文件能够看到具体的描述文档，以下：

　　

　　从新生成项目，就要能够看到完整的接口描述了。例如咱们心中一个TestController以下：

    /// <summary>
    /// 测试控制器
    /// </summary>
    public class TestController : ApiController
    {
        /// <summary>
        /// 测试Get方法
        /// </summary>
        /// <remarks>测试Get方法</remarks>
        /// <returns></returns>
        [HttpGet]
        public string Get()
        {
            return "Get";
        }

        /// <summary>
        /// 测试Post方法
        /// </summary>
        /// <param name="name">姓名</param>
        /// <param name="age">年龄</param>
        /// <remarks>测试Post方法</remarks>
        /// <returns></returns>
        [HttpPost]
        public string Post(string name, int age)
        {
            return name + age.ToString();
        }
    }

　　生成的页面以下，能够看到接口的描述，点击Try it out 便可调用：

　　

3、非依赖代码

　　上面的方式依赖于Swashbuckle包，它已经包含了Swagger-UI组件。咱们的代码须要引入这个包，实际上也能够不须要在项目中引入，单独部署Swagger,包括Swagger-Ui（api展现） 和 Swagger-Editor（在线编辑器），它须要依赖nodejs环境，因此须要先按照nodejs。部署其实也很简单，例如这是我部署的结果：

　　swagger-editor:　　

　　swagger-ui:

　　编辑后只须要将文件保存为json文件，而后拷贝到指定的目录便可。这个部署也很是简单，具体能够参照：

　　1.http://www.raye.wang/2016/09/29/swaggerhuan-jing-da-jian-zhi-fei-yi-lai-dai-ma-fa/?utm_source=tuicool&utm_medium=referral

　　2.http://blog.csdn.net/ron03129596/article/details/53559803

4、总结

　　规范化api的编写和注释，以及标准化文档，对于团队的开发效率有很大的提高，也有利于项目的维护。例如使用在线接口文档后，测试人员测试只须要在页面输入参数，点击调用就能够看到调用结果。

　　swagger 也有在线版的，不须要要本身部署。实际上非代码依赖的方式反而更麻烦，使用代码依赖的方法能够像平时咱们写注释同样就能够，既能在程序里描述，方便开发人员了解接口功能，也能够在在线展现，发布调用方和测试人员调用。