Api接口文档管理工具，你知道哪些呢？

上周看到有人在我的Github开源项目中提了个issue，说是否考虑接入swagger。那今天我就用swagger与其他接口文档工具做对比，同时说说Api接口文档工具的那点事。如今，在前后端分离开发的这个年代，Api接口文档管理工具越来越显得重要。完整的Api接口文档能大大提升前后端开发协作的效率。

image

目前市场有哪些比较优秀的接口文档管理工具呢？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
@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，

image

再看看刚配置的接口：

image

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文档，导出离线版文档。

image

项目Api接入：

只需在Apizza官网（https://apizza.net）申请账号，创建项目，并手写添加接口文档。

主要功能

1. api跨域调试量身定制的chrome插件，本地，在线接口，都可以调。

2. 云端存储，企业安全版支持本地数据中心。

3. 一键分享，与团队共享你的API文档。

4. 支持Postman，Swagger格式 导入Postman/Swagger Json 生成文档。

5. 导出离线文档，部署本地服务器。

6. api Mock 根据文档自动生成返回结果，提供独立URL方便前端测试。

7. 支持多种文档 http接口文档，markdown说明文档。

Apizza接口文档工具有一个很大不足的地方，那是Apizza个人免费版有人数****限制，所有超过8人的团队如果想免费用，你是不用考虑Apizza的。如果你看到有文章或公众号上说Apizza是免费的，那简直是胡扯，他肯定没用过。当然如果你不缺钱，可以付费开通企业版。我们团队也是用了半年多Apizza，后来由于人员增加，Apizza里又无法再新添加新成员，迫使我们不得不放弃Apizza。

image

三，Yapi

Yapi是去哪儿网开源的一款接口管理工具。Yapi旨意将接口作为一个公共的可视化的方式打通前端、后台、测试环节，整合在一块，共同使用维护，提高接口的维护成本。Yapi是一款免费开源的Api接口文档工具，需要下载部署在自己的服务器上。Yapi也是我们现在正在使用的接口文档工具。

image

image

主要特点如下：

• 权限管理 YApi 成熟的团队管理扁平化项目权限配置满足各类企业的需求；
• 可视化接口管理 基于 websocket 的多人协作接口编辑功能和类 postman 测试工具，让多人协作成倍提升开发效率；
• Mock Server 易用的 Mock Server，再也不用担心 mock 数据的生成了；
• 自动化测试 完善的接口自动化测试,保证数据的正确性；
• 数据导入 支持导入 swagger, postman, har 数据格式，方便迁移旧项目；
• 插件机制 强大的插件机制，满足各类业务需求；

image

这里关于Yapi的安装就不详细介绍了。Yapi安装需事先安装nodejs、mongodb、git应用。今天主要讲了我们使用过的Api接口文档工具，整体来说，个人感觉这三款都不错。在团队很小的时候，实际那个都能满足需求。但在团队人数慢慢增加时，就需要考虑一些工具的局限性，这也是我们从Swagger到Apizza再到Yapi的原因。当然，除了上面这三个，市面上还有很多其他的Api文档工具。如：eoLinker、ShowDoc、easydoc、MinDoc等。说了这么多，那具体用哪一个呢？这需要根据自己的团队等情况选择一款最适合自己的。

扫码关注公众号，发送关键词获取相关资料：

1. 发送“Springboot”领取电商项目实战源码；

2. 发送“SpringCloud”领取cloud学习实战资料；