接口文档管理解决方案调研及Torna+Smart-doc的使用

一、现状

目前是通过 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

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

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

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

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

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

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

方式2：docker运行

导入数据库，执行mysql.sql

下载公共镜像

docker pull tanghc2020/torna:1.21.0

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

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

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

执行docker命令：

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

浏览器访问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插件

<!-- smart-doc插件 -->
<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>

3. 在代码/resources目录下添加smart-doc.json文件，并且修改配置。

{
  "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
}

参数说明:

• 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：

tag名称	使用描述
@param	对于在Spring Boot接口层，对于简单类型的参数必须在使用@param时写上注释描述，对于Entity类型smart-doc则不会检查
@deprecated	可以在注释中用于标记接口已经废弃，作用同@Deprecated注解
@apiNote	@apiNote是JAVA新增的文档tag,smart-doc使用@apiNote的注释作为方法的详细描述，因此可以使用@apiNote来写一段长注释。如果一个方法不写 @apiNote注释说明，smart-doc直接使用方法默认注释填充
@author	smart-doc会提取代码中@author标注到文档中，@author可以写在方法上也可以写到类上。例如：@author sunyu on 2016/12/6.

smart-doc自定义Tag：

tag名称	描述
@ignore	@ignore 如果@ignore加到方法上，则接口方法不会输出到文档。从1.8.4开始@ignore支持添加到Controller上进行忽略不想生成文档的接口类。@ignore也可以用于方法上忽略某个请求参数。
@required	如果你没有使用JSR303参数验证规范实现的方式来标注字段，就可以使用@required去标注请求参数对象的字段，标注smart-doc在输出参数列表时会设置为true。【不建议使用，以后会删除】
@mock	从smart-doc 1.8.0开始，@mock tag用于在对象基本类型字段设置自定义文档展示值。设置值后smart-doc不再帮你生成随机值。方便可以通过smart-doc直接输出交付文档。
@dubbo	从smart-doc 1.8.7开始，@dubbo tag用于在Dubbo的API接口类上添加让smart-doc可以扫描到Dubbo RPC的接口生成文档。
@restApi	从smart-doc 1.8.8开始，@restApi tag用于支持smart-doc去扫描Spring Cloud Feign的定义接口生成文档。
@order	从smart-doc 1.9.4开始，@order tag用于设置Controller接口或者API入口的自定义排序序号，@order 1就表示设置序号为1。
@ignoreResponseBodyAdvice	从smart-doc 1.9.8开始，@ignoreResponseBodyAdvice tag用于忽略ResponseBodyAdvice设置的包装类。
@download	从smart-doc 2.0.1开始，@download tag用于标注在Controller的文件下载方法上，生成debug页面时可实现文件下载测试。并且支持下载文件带请求头参数测试。
@page	从smart-doc 2.0.2开始，@page tag用于标注在Controller的方法上表示该方法用来渲染返回一个静态页面，生成debug页面时如果发起测试，测试页面会自动在浏览器开启新标签显示页面。
@ignoreParams	从smart-doc 2.1.0开始，@ignoreParams tag用于标注在Controller方法上忽略掉不想显示在文档中的参数，例如：@ignoreParams id name，多个参数名用空格隔开
@response	从smart-doc 2.2.0开始，@response tag标注在Controller方法上可以允许用这自己定义返回的json example。建议只在返回基础类型时使用，如：Result类型这种泛型是简单原生类型的响应。
@tag	@since 2.2.5, @tag用于将Controller方法分类, 可以将不同Contoller下的方法指定到多个分类下, 同时也可以直接指定Controller为一个分类或多个分类，【不要使用，不支持，直接用分组配置代替】

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

mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest -pl :torna-test -am
## 其中-pl :torna-test -am表示推送哪个子模块

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

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

六、总结

• 建议使用统一的分支进行文档推送

• 后面文档稳定了，建议关闭smart-doc.json中的replace，防止文档误操作变更。