API管理工具对比,制定您的API管理平台

有一定工作年限的人一定会接触过通过word文档或者wiki的方式来进行接口对接交流的介质。后来为了方便协作修改接口,又逐渐的开始有人通过markdown文档,提交到版本管理系统的方式来编写接口。

后来随着浏览器的发展,出现了有利于接口调试的插件,最常见的就是postman,可以很方便的向接口发起post和get请求,并附加各种请求头和cookie等,并且支持编写接口测试脚本来做接口测试。您也可以把postman当做接口文档来使用,但是作为团队工具还是不太方便,并且是收费的。

后来出现了一个框架级的接口工具:swagger。可以通过代码注解自动生成文档的源文件(swagger.json),然后渲染成ui,通过ui界面查看接口,以及进行接口调用。

同时也有一些第三方开源的接口系统开始涌现:

  • RAP:阿里开发的RAP,是一个可视化接口管理工具 通过分析接口结构,动态生成模拟数据,校验真实接口正确性,围绕接口定义,通过一系列自动化工具提升我们的协作效率。可以通过RAP按照项目来管理接口,在线编辑接口,方便团队共享,同时会根据接口文档生成mock接口,方便接口调试。
  • Yapi:去哪里开发的高效、易用、功能强大的API管理平台,提供项目管理,接口管理,MockServer,在线调试功能,支持swagger文档的导入。

对比下各个工具:

接口工具 在线调试 mock数据 项目管理 团队协作 易维护
Word文档 × × ×
Markdown × × × 一般,编辑需要解决冲突 较差
Postman 支持,但配置稍微繁琐 一般 一般
Swagger 支持,但需要自己搭建服务器 较好 较好
RAP × 支持,可以灵活配置 较好
YAPI 支持,可以灵活配置 较好

该对功能支持列表编写于2018年12月份

对比下来,YAPI是比较合理的接口管理工具。对于之前通过Swagger工具来维护接口的项目,这里提供一个便捷的方法快速把项目中的swagger导入到YAPI项目中。

配置项目自动生成swagger json文件

首先,您的项目应该引入swagger相关jar包,并且在相关的RPC接口(需要支持rest)或者网关接口中编写了swagger文档注解:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<!-- swagger start -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-core</artifactId>
</dependency>
<!-- swagger end -->

然后,您的项目需要引入swagger maven插件,用于生成swagger.json文件:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<!-- swagger 接口json文件生成插件 start -->
<plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>3.1.8-SNAPSHOT</version>
<configuration>
<apiSources>
<apiSource>
<info>
<title>Swagger接口文档</title>
<version>v1</version>
<description>
Swagger接口文档
</description>
</info>
<locations>
<locatin>com.kingdee.finance.fixin</locatin>
</locations>
<securityDefinitions>
<securityDefinition>
<name>basicAuth</name>
<type>basic</type>
</securityDefinition>
</securityDefinitions>
<jsonExampleValues>true</jsonExampleValues>
<outputFormats>json</outputFormats>
<swaggerDirectory>${basedir}</swaggerDirectory>
<swaggerApiReader>com.github.kongchen.swagger.docgen.reader.JaxrsReader</swaggerApiReader>
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- swagger 接口json文件生成插件 end -->

注意,可能最新版本的jar包可能还没部署到maven中央仓库,您可以从github下载项目编译推送到私服,您也可以从这里下载3.1.8-SNAPSHOT版本的jar包:

链接: https://pan.baidu.com/s/18qdCayzL9u-pSwKMLy59tw
提取码: 4hxw

编译项目,即可在项目根目录下生成swagger.json文件。具体生成目录地址可以通过插件的swaggerDirectory配置项进行配置。

YAPI导入Swagger接口

按照官网的文档使用命令进行操作即可:通过命令行导入接口数据

maven构建后自动触发导入swagger到YAPI

在Jenkins构建完成之后,会在项目根目录生成swagger.json文件,只需要在Jenkins的任务的Post Steps步骤中,添加以下Shell即可:

1
2
cd $WORKSPACE/$project
yapi import

其中$project为Jenkins参数化构建的时候传入的项目文件夹名称变量。

更多的环境设置,接口mock,在线调试,集成LDAP账号等功能正在等着你去发掘。

arthinking wechat
欢迎关注itzhai公众号,欢迎关注itzhai公众号,获取更多最新的文章