接口管理平台私有化部署smart-doc + Torna 保姆级教学

smart-doc + Torna 保姆级教学

Smart-Doc集成

直接看smart-doc官网也可以的：https://smart-doc-group.github.io/#/zh-cn/start/quickstart

第一步：在项目resource目录下创建smart-doc.json文件

{
//  "serverUrl": "http://dc-dss.yeemiao.net/web", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
  "pathPrefix": "", //设置path前缀,非必须。如配置Servlet ContextPath 。@since 2.2.3
  "isStrict": false, //是否开启严格模式
  "allInOne": true,  //是否将文档合并到一个文件中，一般推荐为true
  "outPath": "./src/main/resources/static/doc", //指定文档的输出路径
  "coverOld": true,  //是否覆盖旧的文件，主要用于mardown文件覆盖
  "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
  "packageFilters": "com.smy.smyx.uts.oms.controller.*",//controller包过滤，多个包用英文逗号隔开，2.2.2开始需要采用正则：com.test.controller.*
  "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
  "style":"xt256", //基于highlight.js的代码高设置,可选值很多可查看码云wiki，喜欢配色统一简洁的同学可以不设置
  "projectName": "uts-oms后台",//配置自己的项目名称
  "skipTransientField": true,//目前未实现
  "sortByTitle":false,//接口标题排序，默认为false,@since 1.8.7版本开始
  "showAuthor":true,//是否显示接口作者名称，默认是true,不想显示可关闭
  "requestFieldToUnderline":false,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  "responseFieldToUnderline":false,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  "inlineEnum":true,//设置为true会将枚举详情展示到参数表中，默认关闭，//@since 1.8.8版本开始
  "recursionLimit":7,//设置允许递归执行的次数用于避免一些对象解析卡主，默认是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
  "urlSuffix":"",//支持SpringMVC旧项目的url后缀,@since 2.1.0
  "displayActualType":false,//配置true会在注释栏自动显示泛型的真实类型短类名，@since 1.9.6
  "ignoreRequestParams":[ //忽略请求参数对象，把不想生成文档的参数对象屏蔽掉，@since 1.9.2
  ],
  "customResponseFields": [ //自定义添加字段和注释，一般用户处理第三方jar包库，非必须
  ],
  "appToken": "637a1501ffb54a1e873e7053cdc086d6", //torna平台appToken,@since 2.0.9
  "openUrl": "http://torna.smyoa.com/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"测试环境", //torna环境名称
  "debugEnvUrl":"http://192.168.2.7:8084/uts-oms/",//推送torna配置接口服务地址,可用于http调用controller接口
  "tornaDebug":true, //启用会推送日志
  "requestHeaders": [{ //设置请求头，没有需求可以不设置
    "name": "Sit-Token",//请求头名称
    "type": "string",//请求头类型
    "desc": "请求token",//请求头描述信息
    "value":"",//不设置默认null
    "required": false,//是否必须
    "since": "-",//什么版本添加的改请求头
    "pathPatterns": "",//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
    "excludePathPatterns":""//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
  }]
}

可以根据注释修改一下对应的配置，目前我们要修改的主要有：packageFilters ，projectName，appToken，debugEnvUrl，requestHeaders，根据项目适当修改配置即可。

其中，appToken对应torna 项目模块【OpenAPI】-【token】，这个必须要填对，如果是首次接入，需在左侧【+】中先新创建自己的项目模块，以获取到模块的token。

第二步：在pom文件中添加smart-doc插件

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

这里需要修改自己的 finalName，如果有引入外部第三方依赖，并且在接口文档上展示其注释的时候，则需要在 includes 标签下引入相应的服务即可。

日常使用：

1.代码中正常写注释就可以了，方法注释可以参考下面链接，在idea设置相应注释模板，方便生成标准的注释。https://blog.csdn.net/qinqigang/article/details/79071486  

2. 需要生成文档时，执行start-doc的maven插件就可以了，文档自动发布到torna上

3. 参考项目：uts-oms 的 feature_20220728_torna分支