原文地址

一、现状

目前是通过 swagger + knife4j 的方式集成到微服务项目中，后端同学在开发或修改接口后，需要手动同步维护至公司内部的 wiki 中供前端和测试同学们查阅。

目前来说，这种现有方式存在如下的几个问题：

1. 接口调试和在线文档依赖服务的启动。
2. 现有服务基于 k8s，服务是无状态的，无固定 IP，文档查看需要配置映射。
3. 一般开发同学比较习惯使用 Markdown 语言（.md）撰写文档，但是公司 wiki 平台不支持导入 md 文件，因此需要开发同学手动添加 wiki，效率过低。
4. Api 更新不及时或未更新。主要由于接口文档依赖于注解的更新，wiki 也需要人工进行更新维护，难免发生疏漏。
5. 公司内部跨部门接口对接时，存在某些接口 wiki 无权限，需要项管协助开通或者需要我们手动把 wiki 中的接口文档以 word 的形式导出，工作效率比较低，并且也存在文档变更不及时通知的场景。
6. 与第三方对接时，公司内部的 wiki 由于是内网，而且需要登录。所以文档都是通过 word 导出的方式，每次接口变更都需要同步修改 wiki 后，在导出一份 word 出来提供给第三方。

二、需求

后端同学角度：

• 减少撰写接口文档上的时间花销，提高工作效率。有这个时间去优化优化代码，优化优化注释不是最好嘛。
• 现有服务过多，文档不方便集中管理。目前 wiki 都是按照业务去撰写的，开发在撰写接口文档时，基本上是各写各的，导致 wiki 目录接口层级比较乱。期望可以有一个更好 集中管理文档 的平台，方便按照微服务归类。
• 可以提供 在线接口调试 的功能。

前端同学角度：

• 接口 文档清晰 有条理，格式统一 化。现有 wiki 维护可以说是百花齐放，有些人文档写的比较清晰，有些人就写的很随意。不利于接口对接，影响开发效率。
• 接口文档最好可以 支持 Mock 与调试。当开发工期短的时候，后端开发只能先把接口定义出来，由于逻辑未完成，所以前端没法进行接口的调试。
• 文档更新及时。当接口变动某些参数时，可以在文档上很好的体现出来，便于前端同步维护代码。

测试同学角度：

• 文档的 稳定性 可以得到保证，持续查阅。由于目前项目组使用的是 knife4j 的方式，接口文档基于服务的启动，所以在线接口文档非高可用的。
• 接口文档变更有 消息通知与变更记录 ，方便接口及时对接与文档 溯源，省的与后端扯皮。
• 对接灵活，最好可以对接到公司层面的 QC 平台。

项目管理 角度：

• 有统一的文档管理平台，各个部门可以很好的协同，同时有较为 合理的权限控制。
• 在对接三方公司时，可以很方便的提供接口文档给第三方，分享方式灵活多样。

公司角度：

• 文档 保证安全性 ，最好可以在公司层面 私有化部署 ，同时 减少成本 开销。

三、调研

Swagger

官方地址

https://swagger.io/

介绍

swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为 17 年发布的 Swagger3（Open Api3）。

同时 Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，并于 2015 年重命名为 OpenApi。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Knife4j

官方地址

https://doc.xiaominfo.com/knife4j/

介绍

knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案, 前身是 swagger-bootstrap-ui, 取名 knife4j 是希望她能像一把匕首一样小巧, 轻量, 并且功能强悍!

knife4j 的前身是 swagger-bootstrap-ui，为了契合微服务的架构发展, 由于原来swagger-bootstrap-ui 采用的是后端 Java 代码 + 前端 Ui 混合打包的方式, 在微服务架构下显的很臃肿, 因此项目正式更名为knife4j

Apifox

官方地址

https://www.apifox.cn

文档：https://apifox.com/help/

介绍

Apifox 是集 API 文档、API 调试、API Mock、API 自动化测试多项实用功能为一体的 API 管理平台，定位为 Postman + Swagger + Mock + JMeter。旨在通过一套系统、一份数据，解决多个工具之间的数据同步问题。只需在 Apifox 中定义 API 文档；API 调试、API 数据 Mock、API 自动化测试等功能就可以直接使用，无需再次定义。API 文档和 API 开发调试流程在同一个工具内闭环，API 调试完成后即可确保与 API 文档定义完全一致。高效、及时、准确！

Smart-doc + Torna

官方地址

smart-doc 官方网址：https://smart-doc-group.github.io/#/zh-cn/

Torna 官方网址：https://www.torna.cn/

Torna 整合 smart-doc 教程 https://torna.cn/dev/smart-doc.html

介绍

smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具，smart-doc 在业内率先提出基于 JAVA 泛型定义推导的理念， 完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照 java-doc 标准编写注释， smart-doc 就能帮你生成一个简易明了的 Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+ 的文档。

Torna 是由 smart-doc 官方独家推动联合研发的企业级文档管理系统，因此 smart-doc 官方不会对接其它任何的外部文档管理系统，例如像 showdoc、yapi 之类的对接请自定内部处理。

smart-doc 是一个文档推导工具，可以根据原生的 javadoc 及自定义的一些 javedoc 生成多种格式的接口文档。而 Torna 是一个文档管理平台，官方提供了很好的聚合方案，例如：使用 smart-doc 的插件方式（下面会说到）。

EasyYapi + Yapi

官方地址

Yapi： http://yapi.mglicai.com/

Yapi 文档： http://hellosean1025.github.io/yapi

EasyYapi：https://easyyapi.com/

介绍

YApi 是由去哪儿网移动架构组(简称 YMFE，一群由 FE、iOS 和 Android 工程师共同组成的最具想象力、创造力和影响力的大前端团队) 开发的可视化接口管理工具，是一个可本地部署的、打通前后端及 QA 的接口管理平台。

YApi 旨在为开发、产品和测试人员提供更优雅的接口管理服务，可以帮助开发者轻松创建、发布和维护不同项目，不同平台的 API。有了 YApi，我们可以很方便的测试、管理和维护多个项目的 API 接口，不像 Swagger 那样是随应用生和灭的(且线上环境下大多数须关闭)，YApi 是一个独立的服务平台。

EasyYapi 是一款 Idea 插件，帮你导出 API 到 YApi、postman、markdown。

Yapi 参考安装：https://mp.weixin.qq.com/s?\_\_biz=MzA4ODIyMzEwMg==&mid=2447536869&idx=1&sn=5cf1a994e428312054ff5e015f0a57dd&chksm=843baef4b34c27e2be91e4216f44710f3e40c6b2ac2ea82c27e2eac509ae8330d09dfcf2577e&scene=21#wechat\_redirect

EasyYapi 的使用参考文档：https://mp.weixin.qq.com/s?\_\_biz=MzA4ODIyMzEwMg==&mid=2447536892&idx=1&sn=b49f4f39ae39c83744f27df29e41a107&chksm=843baeedb34c27fb712b1b21bdd37891ca82249838b87f7aaf042ad9835dcb98ddd21f44c731&cur\_album\_id=2329480871705296897&scene=189#wechat\_redirect

四、对比

（一）Swagger

1、部署方式

本地化部署

2、优点

• 基于 RESTFUL 风格
• 项目集成简单
• 支持多语言（java，go，python 等）

3、缺点

• 依赖于服务的启动
• 依赖注解
• 存在多个服务的时候不便于统一管理
• 界面比较简单，接口和响应对象分开展示，参数字典对照不方便。
• 不支持自定义的请求头

4、分享方式

• 支持 openapi 分享

（二）Knife4j

1、部署方式

本地化部署

2、优点

• 在 swagger 基础上，做了增强，UI 更加直观。
• 比 swagger 支持了导出 markdown，html，word 格式的离线文档。
• 支持自定义的请求头。
• 支持多种 java 框架。
• 有细微的版本控制，识别后端接口的新增与修改。

3、缺点

• 导出只支持全量导出
• 功能相对比较单一
• 依赖于服务的启动
• 依赖注解
• 存在多个服务的时候不便于统一管理
• 个人的开源项目

4、分享方式

• 支持 markdown，html，word，openapi 导出。

（三）Apifox

1、部署方式

免费是 Saas 版，私有版需要付费

2、优点

功能丰富，包括文档管理、接口调试、Mock、接口自动化测试等 商业软件，更新和维护比较稳定。 有桌面版和 web 版，桌面版功能比较全 免费版可用，基本无限制 方便集成 Swagger 和 Springdoc

3、缺点

免费是 Saas 版，需要进行定期的账号管理，防止泄露。同时接口的安全风险可能需要进一步考虑

4、分享方式

支持 App、网页访问、支持网页分享 支持导出静态文档（但是目前不支持直接导出 word）。

（四）Smart-doc + Torna

1、部署方式

国产开源项目，私有化本地部署。支持 windows，linux，docker，k8s 多种方式。

2、优点

• smart-doc 基于 javadoc 的方式推导出接口文档，对代码的侵入性低。
• torna 支持 smart-doc 插件、swagger 插件、openapi 多种方式集成文档。
• torna 为开源项目，部署成本低。
• torna 的社区相对活跃（亲测！在群里问了一些问题，作者及时响应并答复）
• torna 可以满足目前大多数现有需求场景。
• torna 基于 java+vue 开发，项目组技术栈相对成熟，方便后续二开。

3、缺点

• 国产开源项目，存在作者后续不维护的风险。
• torna 目前不支持 openAPI 的导出方式（不过 smart-doc 是支持的）

4、分享方式

• 支持网页分享。可以分享公开链接或带秘钥的私有链接。
• 支持 markdown，html，doc 导出。

（五）EasyYapi + Yapi

1、部署方式

支持本地化部署，支持 Docker 部署

2、优点

功能丰富，包括文档管理、接口调试、Mock。 方便集成 Swagger 和 Springdoc。

Yapi 有较为细致的权限管理。

3、缺点

Yapi 目前已经不怎么维护更新了，社区活跃度较低

4、分享方式

支持 App、网页访问、支持网页分享 支持导出静态文档（但是目前不支持直接导出 word）。

五、选择与使用

基于以上的对比，加上目前公司的开发方式，最后选型 smart-doc + Torna 实现文档全流程自动化。

原因如下：

1. 使用 javadoc 注释的方式代替侵入性注解，可以简化代码结构，规范代码注释。
2. 由于目前微服务过多，需要一个聚合平台统一管理，且文档不依赖于项目的启动。
3. 国内开源项目，可以本地化部署，安全性能得到保证。
4. 可以以项目组的形式管理接口，各项目组之间接口互不影响。权限划分细致，便于团队文档可见性管理。
5. 有丰富的文档导出功能。
6. 现有项目使用 smart-doc 的 maven 插件可以很方便的推送接口文档到 torna 中，改造成本相对较低。

安装部署 torna

方式 1：下载 zip 本地运行

• 准备工作
  • Java 环境，最低要求 Java8
  • MySQL，要求 5.6.5 及以后，5.6.5 之前的版本见：支持低版本 MySQL

前往 发行版页面 ，下载最新版本，解压 zip

导入数据库，执行mysql.sql

打开 application.properties 配置文件，修改数据库连接配置

执行 sh startup.sh 启动（Windows 执行startup.bat）

访问：http://ip:7700

• 登录账号：

用户名：admin，密码：123456

• 后续升级

无特殊说明，只需要覆盖 torna.jar 文件 和dist 文件夹，然后重启即可

Linux 服务器快速部署

• 前提：导入数据库，执行mysql.sql

创建配置文件，执行命令：

1
2
3
4
5

`mkdir /etc/torna && wget https://gitee.com/durcframework/torna/raw/master/install/application.properties -O /etc/torna/application.properties` 

*   1

vim /etc/torna/application.properties修改数据库连接配置

拉取最新版本并启动，以 1.21.0 为例

1
2
3
4
5

`wget https://gitee.com/durcframework/torna/raw/master/install/restart-torna.sh && sh restart-torna.sh 1.21.0` 

*   1

后续更新版本只需执行sh restart-torna.sh 版本号

方式 2：docker 运行

导入数据库，执行mysql.sql

下载公共镜像

1
2
3
4
5

`docker pull tanghc2020/torna:1.21.0` 

*   1

创建配置文件，执行命令：

1
2
3
4
5

`mkdir /etc/torna && wget https://gitee.com/durcframework/torna/raw/master/install/application.properties -O /etc/torna/application.properties` 

*   1

vim /etc/torna/application.properties修改数据库连接配置

执行 docker 命令：

1
2
3
4
5
6
7
8
9
10
11
12
13

`docker run --name torna --restart=always \
  -p 7700:7700 \
  -e JAVA_OPTS="-server -Xms512m -Xmx512m" \
  -v /etc/torna/application.properties:/torna/config/application.properties \
  -d tanghc2020/torna:1.21.0` 

*   1
*   2
*   3
*   4
*   5

浏览器访问http://ip:7700，ip 对应 docker 宿主机器 ip，非 docker 容器 ip

运维脚本

docker-compose 部署 torna

【docker-compose 方式部署 torna】

kubernetes 部署 torna

【kubernetes 部署 torna】

代码集成 smart-doc 插件实现推送

1. 先在 torna 上创建对应的应用

2. 在代码里，pom.xml 添加 smart-doc 的 maven 插件

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

 `<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.4.9</version>
    <configuration>
        
        <configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
        </execution>
    </executions>
</plugin>` 

*   1
*   2
*   3
*   4
*   5
*   6
*   7
*   8
*   9
*   10
*   11
*   12
*   13
*   14
*   15

3. 在代码 /resources 目录下添加 smart-doc.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

`{
  "outPath": "target/doc",
  "projectName": "torna-test",
  "packageFilters": "com.tmzh.apidoc.torna.web.controller.*",
  "openUrl": "http://localhost:7700/api",
  "appToken": "7af425085ee94d7d8b74d4074e51af32",
  "debugEnvName":" 本地环境 ",
  "debugEnvUrl":"http://127.0.0.1:8080",
  "tornaDebug": true,
  "replace": true
}` 

*   1
*   2
*   3
*   4
*   5
*   6
*   7
*   8
*   9
*   10
*   11

参数说明:

• outPath：固定填这个不用变
• projectName：项目名称
• packageFilters：Controller 接口对应的 package 目录，多个用 , 隔开
• openUrl：Torna 中的 OpenAPI 接口
• appToken：Torna 中的 OpenAPI token
• debugEnvName：Torna 中调试环境名称
• debugEnvUrl：Torna 中调试环境地址
• tornaDebug：是否开启调试，初次使用建议开始，后面稳定了关闭
• replace：是否替换文档，建议 true

这里是快速配置，完整版的配置参考：https://smart-doc-group.github.io/#/zh-cn/diy/config

4. 参考 smart-doc 中 javadoc 规范，对代码进行规范化注释。

参考：https://smart-doc-group.github.io/#/zh-cn/start/javadoc

smart-doc 支持的原生 javadoc：

smart-doc 自定义 Tag：

5. 双击右侧 maven 插件栏中的 smart-doc:torna-rest 实现文档推送，当然也可以使用 maven 的命令行模式，如下

1
2
3
4
5
6

`mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest -pl :torna-test -am` 

*   1
*   2

对于 maven 多模块项目，推荐使用命令行的形式，推送某个具体的服务至 torna。可以参考：

maven 多模块中使用插件 示例如下：

六、总结

后端同学：

• 【推荐】对历史服务建议完善相应的 tag 注释（smart-doc 方式），或 swagger 注解（swagger 插件方式）。
• 【强制】对新服务、新接口，需要编写 openapi 注解（swagger）或 javadoc 注释（smart-doc），便于后续文档维护。
• 【强制】在开发阶段，使用统一的分支进行文档推送，防止出现分支代码不一致的场景。
• 【强制】后面文档稳定了，关闭 smart-doc.json 中的 replace，防止文档误操作变更。

前端同学：

• 【推荐】对与前端同学来说，在版本开发时，需要及时关注版本迭代接口，并在个人中心绑定钉钉手机号，这样可以在文档群中接收到来自钉钉机器人的 @消息。

测试同学：

• 【推荐】对与测试同学来说，在版本提测后，需要及时关注版本迭代的接口，并在个人中心绑定钉钉手机号，这样可以在文档群中接收到来自钉钉机器人的 @消息。
• 【推荐】torna 平台在最近的版本中，支持了 MeterSphere 平台的接口文档推送（可能存在些许问题）。自动化测试同学可以在空间中配置 MeterSphere 相关配置。每当接口变更时，及时查看 MeterSphere 的相关空间接口是否同步变更，确保接口变更同步及时。