上周看到有人在我的Github开源项目中提了个issue，说是否考虑接入swagger。那今天我就用swagger与其他接口文档工具做对比，同时说说Api接口文档工具的那点事。如今，在前后端分离开发的这个年代，Api接口文档管理工具越来越显得重要。完整的Api接口文档能大大提升前后端开发协作的效率。
目前市场有哪些比较优秀的接口文档管理工具呢？Swagger Api接口文档工具到底如何，我大致汇总一下吧！
一、Swagger
说到Swagger，他确实是为开发者发明的一款神器，他可以实现自动生成 API 接口文档，在线调试，非常的方便。Swagger 官方文档: https://swagger.io/。项目接入：pom依赖：
<!-- swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency>配置信息：
@Configuration@EnableWebMvc@EnableSwagger2public class SwaggerConfig extends WebMvcConfigurerAdapter { @Bean public Docket buildDocket() { Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()); docket = docket.select() .apis(RequestHandlerSelectors.any())//controller路径 .paths(PathSelectors.any()).build(); return docket; } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler('swagger-ui.html') .addResourceLocations('classpath:/META-INF/resources/'); registry.addResourceHandler('/webjars/**') .addResourceLocations('classpath:/META-INF/resources/webjars/'); } private ApiInfo buildApiInf() { return new ApiInfoBuilder() .title('RestAPI Docs') .termsOfServiceUrl('http://www.github.com/kongchen/swagger-maven-plugin') .build(); }}Controller里的配置（例如）：
@Api(value='客户API',tags={'客户API'})@RestController@RequestMapping('/api/customer/')public class CustomerController { /** * 更新采购商资料 * * @return * @throws Exception */ @ApiOperation(value='更新商户信息', notes='根据Customer对象更新,SON格式：{\'id\':1,\'customerType\':\'..\',...}') @ApiImplicitParam(name = 'Json', value = '', dataType = 'Json',required = true) @ResponseBody @RequestMapping(value='update', method=RequestMethod.POST, produces = {'application/json;charset=UTF-8'}) public JSONObject updateCustomer(HttpServletRequest request) throws Exception{ //TODO 代码逻辑 }}启动项目，打开swagger,界面：http://192.168.1.101:9001/swagger-ui.html，
再看看刚配置的接口：
Swagger的接入特别简单，还可以在线调试。那么Swagger一定就很牛逼吗，我们再看看他的优缺点。
Swagger的优点如下：
1、节省了大量手写接口文档的时间，这是最大的优势；
2、生成的接口文档可以直接在线测试，节省了使用Postman设置接口参数的过程，而且请求的参数，返回的参数一目了然；
3、接口按照模块已经分类展示，结构清晰；
Swagger 的缺点****大致如下：
1、需要在代码中写大量的注解，生成的接口文档越清晰，写的注解越多；
2、对于复杂功能，一个功能需要多个模块配合的情况下，联调测试将会是一件非常麻烦的事。Swagger还不支持自定义接口文档，不能指明某一个功能需要使用哪些接口；
3、对于返回结果不能添加说明或者实现这个功能非常麻烦。虽然 Swagger 有 @ApiResponse注解用来说明返回结果，但是这个使用并不方便，而且如果返回的并不是对象的时候(如 Map)，就无法实现给每一个返回字段的说明；
4、无法测试错误的请求方式、参数等。如接口指定使用 POST 请求，则无法使用 swagger 测试 GET 请求的结果，也无法自定义 Header；
5，分布式开发环境中，一个项目往往有多个接口服务（比如电商项目有app，pc，后台三个接口服务）。每一个接口服务都对应一个独立的swagger文档，不能实现统一整合。
**二，apizza **
Apizza也是我们项目中使用过的，是从Swagger 转到Apizza。而却他是极客专属的api协作管理工具，免费的团队协作，在线模拟调试，快速生成api文档，导出离线版文档。
项目Api接入：
只需在Apizza官网（https://apizza.net）申请账号，创建项目，并手写添加接口文档。
api跨域调试量身定制的chrome插件，本地，在线接口，都可以调。
云端存储，企业安全版支持本地数据中心。
一键分享，与团队共享你的API文档。
支持Postman，Swagger格式 导入Postman/Swagger Json 生成文档。
导出离线文档，部署本地服务器。
api Mock 根据文档自动生成返回结果，提供独立URL方便前端测试。
支持多种文档 http接口文档，markdown说明文档。
Apizza接口文档工具有一个很大不足的地方，那是Apizza个人免费版有人数限制，所有超过8人的团队如果想免费用，你是不用考虑Apizza的。如果你看到有文章或公众号上说Apizza是免费的，那简直是胡扯，他肯定没用过。当然如果你不缺钱，可以付费开通企业版。我们团队也是用了半年多Apizza，后来由于人员增加，Apizza里又无法再新添加新成员，迫使我们不得不放弃Apizza。
三，Yapi
Yapi是去哪儿网开源的一款接口管理工具。Yapi旨意将接口作为一个公共的可视化的方式打通前端、后台、测试环节，整合在一块，共同使用维护，提高接口的维护成本。Yapi是一款免费开源的Api接口文档工具，需要下载部署在自己的服务器上。Yapi也是我们现在正在使用的接口文档工具。
主要特点如下：
权限管理 YApi 成熟的团队管理扁平化项目权限配置满足各类企业的需求；
可视化接口管理 基于 websocket 的多人协作接口编辑功能和类 postman 测试工具，让多人协作成倍提升开发效率；
Mock Server 易用的 Mock Server，再也不用担心 mock 数据的生成了；
自动化测试 完善的接口自动化测试,保证数据的正确性；
数据导入 支持导入 swagger, postman, har 数据格式，方便迁移旧项目；
插件机制 强大的插件机制，满足各类业务需求；
这里关于Yapi的安装就不详细介绍了。Yapi安装需事先安装nodejs、mongodb、git应用。今天主要讲了我们使用过的Api接口文档工具，整体来说，个人感觉这三款都不错。在团队很小的时候，实际那个都能满足需求。但在团队人数慢慢增加时，就需要考虑一些工具的局限性，这也是我们从Swagger到Apizza再到Yapi的原因。当然，除了上面这三个，市面上还有很多其他的Api文档工具。如：eoLinker、ShowDoc、easydoc、MinDoc等。说了这么多，那具体用哪一个呢？这需要根据自己的团队等情况选择一款最适合自己的。
联系客服
