smart-doc+torna实现完全无侵入的java Rest Api文档生成工具

本流程针对smart-doc自动生成dubbo接口文档，其他模式流程类似，可根据文档自行摸索

smart-doc源码地址

[torna源码地址](torna: 企业接口文档解决方案，目标是让文档管理变得更加方便、快捷。Torna采用团队协作的方式管理和维护项目API文档，将不同形式的文档纳入进来，形成一个统一的维护方式。 (gitee.com))

一. 集成

引入maven插件

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.1.6</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试</projectName>
        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
        <excludes>
            <!--格式为：groupId:artifactId;参考如下-->
            <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>

添加依赖

<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>2.1.6</version>
    <scope>test</scope>
</dependency>

二. 配置文件

resources下创建json文件

{
  "serverUrl": "", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
  "isStrict": true, //是否开启严格模式
  "allInOne": true,  //是否将文档合并到一个文件中，一般推荐为true
  "outPath": "D://md2", //指定文档的输出路径
  "coverOld": true,  //是否覆盖旧的文件，主要用于mardown文件覆盖
  "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
  "style":"xt256", //基于highlight.js的代码高设置,可选值很多可查看码云wiki，喜欢配色统一简洁的同学可以不设置
  "projectName": "platform-provider-base-api",//配置自己的项目名称

  "recursionLimit": 3,//设置允许递归执行的次数用于避免一些对象解析卡主，默认是7，正常为3次以内，//@since 1.8.8版本开始
  "allInOneDocFileName": "index.html",//自定义设置输出文档名称, @since 1.9.0
  "requestExample": "true",//是否将请求示例展示在文档中，默认true，@since 1.9.0
  "responseExample": "true",//是否将响应示例展示在文档中，默认为true，@since 1.9.0

  "appKey": "20210514842707636985004032",// torna平台对接appKey,, @since 2.0.9
  "appToken": "e74fd4bca52c4e1682f0306d6a8b66be", //torna平台appToken,@since 2.0.9
  "secret": "NTE$MJf%ZRY4uii3tFtvRlAT1-.ajn2%",//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配置接口服务地址
  "tornaDebug": false,//启用会推送日志
  "ignoreRequestParams":[ //忽略请求参数对象，把不想生成文档的参数对象屏蔽掉，@since 1.9.2
    ""
  ],

  "revisionLogs": [{ //文档变更记录
    "version": "1.0", //文档版本号
    "revisionTime": "2021-5-13 18:30", //文档修订时间
    "status": "update", //变更操作状态，一般为：创建、更新等
    "author": "LiChao", //文档变更作者
    "remarks": "文档初始化" //变更描述
  }
  ],

  "rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖，配置后输出到文档方便使用者集成
    "artifactId":"platform-provider-base-api",
    "groupId":"com.esh",
    "version":"1.0.0-SNAPSHOT"
  }]
}

三. 下载并搭建torna

点击下载 最新版软件

执行sql

mysql.sql · tanghc/torna - Gitee.com

修改数据库连接配

编辑torna文件夹下application.properties文件进行配置

启动torna

运行startup.bat （Linux下startup.sh）

四. 生成文档

idea下找到maven --> plugins --> smart-doc --> samt-doc:torna-rpc