接口文档生成：smart-doc+torna

代码规范

smart-doc通过对javadoc注释的源码就行分析，生成html接口文档，然后将文档推送到torna统一展示。故对于代码规范要求很严格。

1.JavaDoc规范。添加类、方法注解

标签	描述	示例
@author	标识一个类的作者	@author description
@exception	标志一个类抛出的异常	@exception exception-name explanation
@param	说明一个方法的参数	@param parameter-name explanation
@return	说明返回值类型	@return explanation
@since	标记当引入一个特定的变化时	@since release
@throws	和 @exception标签一样.	The @throws tag has the same meaning as the @exception tag.
@version	指定类的版本	@version info

 2.IDEA定义注释模板

IDEA类和方法注释模板设置（非常详细）

3.smart-doc对于返回参数、请求参数

入参、出参尽量使用类定义的方式标准化

smart-doc功能使用介绍

---

smart-doc插件加入到maven项目

直接smart-doc官网按照步骤引入插件 ，插件版本目前最新是2.2.1版本。

可以在maven 中央仓库找到smart-doc plugin插件，查看最新版本。

操作

1. 建立smart-doc.json文件，放在resources目录。配置json文件。
2. pom加入plugin插件
3. 运行命令生成或向torna推送文档

 torna部署

Torna 按照官网下载zip版本，使用mysql运行指定sql。

smart-doc与torna对接

smart-doc+torna参考整体流程

springboot集成smart-doc导出接口文档推送到torna

注意

1. idea运行自动推送时，执行torna-rest，不是torna-rpc
2. token必须新建模块后才能获得。模块对应一个项目，空间对应一个项目组。项目组可以有多个项目。
3. 空间--开放用户--新建账户后可以获取appkey/Secret。每个用户一个appkey/Secret，每个项目一个token。

torna步骤

1. 新建空间，一个项目组一个空间。开放用户，新建用户，获取appkey/Secret。
2. 新建项目。 OpenAPI获取项目token。
3. 默认用户名admin@torna.cn 密码 123456

自结项目部署

1.  将smart-doc.json放在spring boot项目的resources文件夹下，修改其中的appKey、secret、token等，这些内容给torna管理员要即可。每个项目一个token，每个用户一个key。

{
  "serverUrl": "http://127.0.0.1", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
  "isStrict": false, //是否开启严格模式
  "packageFilters": "",//controller包过滤，多个包用英文逗号隔开
  "projectName": "smart-doc",//配置自己的项目名称
  "appKey": "20201216788835306945118208",// torna平台对接appKey,, @since 2.0.9
  "appToken": "c16931fa6590483fb7a4e85340fcbfef", //torna平台appToken,@since 2.0.9
  "secret": "W.ZyGMOB9Q0UqujVxnfi@.I#V&tUUYZR",//torna平台secret，@since 2.0.9
  "openUrl": "http://localhost:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"测试环境", //torna测试环境
  "debugEnvUrl":"http://127.0.0.1",//torna
}

1. 将smart-doc的依赖放入到pom文件的plugins中。

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试</projectName>
        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
        <excludes>
            <!--格式为：groupId:artifactId;参考如下-->
            <!--1.0.7版本开始你还可以用正则匹配排除,如：poi.* -->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!--自1.0.8版本开始，插件提供includes支持-->
        <!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
        <includes>
            <!--格式为：groupId:artifactId;参考如下-->
            <include>com.alibaba:fastjson</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
            <phase>compile</phase>
            <goals>
                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

1. 运行推送命令即可。idea：maven---plugin--smart-doc:torna-rest 。eclipse：

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