1.基本介绍

提起接口文档生成和管理的工具，大多数人第一印象都是Swagger。今天要介绍的是一种相对小众的方案：Smart-Doc+Torna。

Smart-Doc是一款接口文档生成工具，可用于生成各种格式的接口文档（如markdown、html，json等等）。
https://github.com/smart-doc-group/smart-doc

Torna是一款接口文档管理工具，可接入各种格式的接口文档，进行可视化管理。http://torna.cn/

相对Swagger，为什么选择Smart-Doc+Torna：

• Swagger需要额外引入依赖到项目中，对API信息的注解比较繁琐，对代码有侵入，遇到复杂一点的API，在Controller里面基本就全是swagger的注解，影响代码可读性。Smart-Doc是基于原生java-doc来生成接口文档，只需要正常写代码注释，就可以生成标准的API文档了。（这也反向规范了开发人员在编写代码过程添加注释）
• Swagger的接口文档管理界面，是内置到应用的，也就是要应用跑起来才能访问，如果应用挂了就访问不了。smart-doc生成接口文档信息后，可通过OpenAPI推送搭配Torna，通过Torna进行文档管理，而Torna是独立部署的，不依赖应用，且可以多个项目共用。

2.Smart-Doc基本使用

相关版本说明：

• SpringBoot版本：2.4.2
• maven版本：3.5.0

2.1.添加配置文件

一般在src/main/resource，添加smart-doc.json文件。（更多配置项可去官网了解）

2.2.添加maven插件配置

在pom.xml文件，添加构建插件配置

<!-- smart-doc  -->
<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.1.8</version>
    <configuration>
        <!--配置文件的路径-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试项目</projectName>
        <excludes>
            <!--如果是多模块项目，可排除依赖的其他模块，不影响接口生成-->
        </excludes>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

2.3.在接口添加注释信息

以下是例子：

2.4.运行效果

测试输出本地html文档：mvn -Dfile.encoding=UTF-8 smart-doc:html

使用IDEA的话，也可以在右侧工具栏直接双击运行也可以

输出效果：

推送到Torna可执行：mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

Torna的使用参考下一章节。

3.Torna的使用

3.1.部署Torna

参考官网的部署文档，可直接用docker部署：
http://torna.cn/dev/config.html#docker添加配置

3.2.新建项目

部署好Torna，然后访问登录并新建好对应的项目。并生成OpenAPI的Token。相关配置需要与smart-doc配置文件中一致

3.3.把接口文档推送到Torna

执行：mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

4.结语

接口文档生成和管理工具有很多种，Swagger功能全面，历史悠久，所以是目前比较主流的解决方案，但也存在对应用代码有侵入性，需要应用强依赖的缺点；技术是发展的，近几年也出了很多新的解决方案，如yapi，smart-doc；还有需要商业化的工具（商业版肯定就做得更好一点）。就开源的方案来说，我个人选择smart-doc+torna，更多的是看中他的轻量性，无侵入性，和基于原生java-doc来解析，这样也间接的要求开发人员多写注释。也欢迎大家交流下其他工具和方案。