上周看到有人在我的Github开源项目中提了个issue，说是否考虑接入swagger。那今天我就用swagger与其他接口文档工具做对比，同时说说Api接口文档工具的那点事。如今，在前后端分离开发的这个年代，Api接口文档管理工具越来越显得重要。完整的Api接口文档能大大提升前后端开发协作的效率。
目前市场有哪些比较优秀的接口文档管理工具呢？Swagger Api接口文档工具到底如何，我大致汇总一下吧！
一、Swagger
说到Swagger，他确实是为开发者发明的一款神器，他可以实现自动生成 API 接口文档，在线调试，非常的方便。Swagger 官方文档: https://swagger.io/。项目接入：pom依赖：
io.springfox
springfox-swagger2
2.4.0
io.springfox
springfox-swagger-ui
2.4.0
配置信息：
@Configuration
@EnableWebMvc
@EnableSwagger2
public 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。
image
三，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等。说了这么多，那具体用哪一个呢？这需要根据自己的团队等情况选择一款最适合自己的。
推荐阅读：
Java项目支付宝支付接入及详解
微信支付之扫码、APP、小程序支付接入详解
SpringBoot电商项目实战 — ElasticSearch接入实现
SpringBoot电商项目实战 — 商品的SPU/SKU实现
SpringBoot电商项目实战 — 数据库服务化切分
扫码关注公众号，发送关键词获取相关资料：
发送“Springboot”领取电商项目实战源码；
发送“SpringCloud”领取cloud学习实战资料；
