一、前言
通常我们的项目会包含许多对外的接口,这些接口都需要文档化,标准的接口描述文档需要描述接口的地址、参数、返回值、备注等等;像我们以前的做法是写在 word/excel,通常是按模块划分,例如一个模块包含 n 个接口,就形成一个文档,然后再用版本控制管理。这样做的缺点是:
1. 不够直观,每次打开文档查看接口很麻烦
2. 文档的维护难度大
3. 调用方和测试人员使用麻烦,需要先去找接口,在用相应的工具测试(例如使用浏览器还可能要安装插件)
我们希望是可以直接在线浏览,然后直接用浏览器测试。而接口的详细描述都在程序里用注释完成。swagger 就可以完成这个工作(ps 好像很多开发人员都还不知道这个东西。。。)。
二、使用 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 即可调用:
三、非依赖代码
上面的方式依赖于 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
四、总结
规范化 api 的编写和注释,以及标准化文档,对于团队的开发效率有很大的提升,也有利于项目的维护。例如使用在线接口文档后,测试人员测试只需要在页面输入参数,点击调用就可以看到调用结果。
swagger 也有在线版的,不需要要自己部署。实际上非代码依赖的方式反而更麻烦,使用代码依赖的方法可以像平时我们写注释一样就可以,既能在程序里描述,方便开发人员了解接口功能,也可以在在线展示,发布调用方和测试人员调用。
来源: http://www.cnblogs.com/4littleProgrammer/p/6713627.html