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文件，添加构建插件配置
com.github.shalousun
smart-doc-maven-plugin
2.1.8
./src/main/resources/smart-doc.json
测试项目
html
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来解析，这样也间接的要求开发人员多写注释。也欢迎大家交流下其他工具和方案。
