相信各位码友，对于swagger都有一番感慨，方便生成文档。生成接口，做调试。但是对代码的入侵严重，容易造成安全隐患以及。多个项目会有多个接口地址，地址混乱不方便统一管理，一个项目一个地址也太割裂。

对于上述现状，其实就需要一个能减少代码的入侵，对没有接入swagger的项目。不用去大改原有的代码，然后还能统一管理接口文档。

由此就有了smart-doc+torna的解决方案。由smart-doc来生成接口文档，整理接口信息，然后交给torna去统一管理你所有项目的接口文档。

smart-doc简介

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

项目接入

先在你本身项目的pom文件里面，引入smart-doc，并按自己项目情况配置一些配置。

   <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.4.5</version>
                <configuration>
                    <!--指定生成文档使用的配置文件-->
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <projectName>${project.description}</projectName>
                    <excludes>
                        <!--格式为：groupId:artifactId;参考如下-->
                        <!--也可以支持正则式如：com.alibaba:.* -->
                        <exclude>net.sf.json-lib.*</exclude>
                        <exclude>com.oracle.*</exclude>
                        <exclude>sun.misc.BASE64Encoder</exclude>
                        <exclude>com.sun.xml.internal.ws.*</exclude>
                        <exclude>io.lions.*</exclude>
                        <exclude>cn.ccvnc.*</exclude>
                    </excludes>
                </configuration>
                <executions>
                    <execution>
                        <!--不需要在编译项目时自动生成文档可注释phase-->
<!--                        <phase>compile</phase>-->
                        <goals>
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

第二步编写smart-doc.json配置文件

{
  "outPath": "./src/main/resources/api", //文档输出路径
  "serverUrl": "http://x.x.x.x", //服务地址，用于绑定torna使用
  "isStrict": false, //是否严格模式
  "allInone": true, //是否将文档合并到一个文件中
  "projectName": "earthquake",
  "coverOld": true,  //是否覆盖旧的文件，主要用于markdown文件覆盖
  "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
  "projectName": "earthquake",//配置自己的项目名称，不设置则插件自动获取pom中的projectName
  "openUrl": "http://x.x.x.x:7700/api", // torna的地址
  "appToken": "f37bc1713ace466eaee45741859b5867",//torna装进啊项目后的token
  "tornaDebug": true,
  "replace": true,
  "isReplace":true, //torna 是否覆盖历史推送 @since 2.2.4
  "tornaDebug":false,//启用会推送日志
  //  "responseBodyAdvice":{ //自smart-doc 1.9.8起，非必须项，ResponseBodyAdvice统一返回设置(不要随便配置根据项目的技术来配置)，可用ignoreResponseBodyAdvice tag来忽略
  //    "className":"com.earthquake.common.core.domain.AjaxResult",
  //    "className":"com.earthquake.common.core.page.TableDataInfo"
  //    //通用响应体
  //  },
  "sortByTitle":false,//接口标题排序，默认为false,@since 1.8.7版本开始
  "showAuthor":true,//是否显示接口作者名称，默认是true,不想显示可关闭
  "requestExample":"true",//是否将请求示例展示在文档中，默认true，@since 1.9.0
  "responseExample":"true" //是否将响应示例展示在文档中，默认为true，@since 1.9.0

}

如此以上，smart-doc就配置完成了。

此时在torna没有部署的时候只能生成一些基础文档，其实并不很美观。最完美的解决就是接入torna。

torna

官网：torna: 接口文档解决方案，目标是让接口文档管理变得更加方便、快捷。Torna采用团队协作的方式管理和维护接口文档，将不同形式的文档纳入进来统一维护。

torna的目标是让文档管理变得更加方便、快捷。Torna采用团队协作的方式管理和维护项目API文档，将不同形式的文档纳入进来，形成一个统一的维护方式。Torna弥补了传统文档生成工具（如swagger）的不如之处，在保持原有功能的前提下丰富并增强了一些实用的功能。

Torna部署

1.有docker的情况

docker pull tanghc2020/latest

2. 无docker情况

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

详细部署可以移步官网进行部署，整体部署也是非常简单，就不再次累述。有问题也可以评论区或者私信问我。

Torna使用

主页

大概页面就是如此，细节大家可以部署后自己尝试。

smart-doc接入torna的

1. 这个有个token
2. 
   

填入后，将ip地址填入，配置就完成了。

推送文档

点击上图按钮即可自动推送到torna

总结

优点：smart-doc根据javadoc格式来的，会强制你代码规范。有助于代码的注释已经后期维护，新手也能很好的看懂项目，鞭策自己的代码风格。

缺点：没有自己好看的ui，必须借助torna才能完美。2.代码规范强，代码不规范会导致文档生成有所偏差

总的来说，利大于弊，比swagger 是好用的。

#夏日生活打卡季#