计划在项目中集成swagger日志框架，经过一顿折腾，发现一个小小的问题。我得springboot框架版本是2.6.13，swagger要匹配这个版本的springboot可能比较麻烦。
这可如何是好……
经跟社区的大神得讨论，他在用的文档生成工具是smart-doc。我尝试一下集成这个工具。
一：添加插件依赖
<!--api文档 begin-->
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.3.5</version>
<configuration>
<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
<configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>smart-doc文档</projectName>
<!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
<excludes>
<!--也可以支持正则式如：com.alibaba:.* -->
<exclude>commons-jxpath:.*</exclude>
<exclude>io.zipkin.brave:.*</exclude>
<exclude>org.apache.kafka:.*</exclude>
<exclude>org.springframework.kafka:.*</exclude>
<exclude>com.netflix.servo:.*</exclude>
</excludes>
<!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有，因此使用时需要注意-->
<!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
<includes>
<!--格式为：groupId:artifactId;参考如下-->
<!--也可以支持正则式如：com.alibaba:.* -->
<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>
<!--api文档 end-->
二：创建配置文件smart-doc.json
{
"serverUrl": "http://127.0.0.1",//指定后端服务访问地址
"outPath": "src/main/resources/static/doc/api",//指定文档的输出路径，生成到项目静态文件目录下，随项目启动可以查看
"isStrict": false,//是否开启严格模式
"allInOne": true,//是否将文档合并到一个文件中
"createDebugPage": false,//是否创建可以测试的html页面
"packageFilters": "com.xxxx.aio.controller.WorkbenchController", //controller包过滤（换成你的路径）
"style": "xt256",//基于highlight.js的代码高设置
"projectName": "smart-doc文档",//配置自己的项目名称
"showAuthor": false,//是否显示接口作者名称
"allInOneDocFileName": "index.html"//自定义设置输出文档名称
}
上边部分的配置就够用。其他部分的配置还有很多，如下：
{
"serverUrl": "http://127.0.0.1", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
"pathPrefix": "", //设置path前缀,非必须。如配置Servlet ContextPath 。@since 2.2.3
"isStrict": false, //是否开启严格模式
"allInOne": true, //是否将文档合并到一个文件中，一般推荐为true
"outPath": "D://md2", //指定文档的输出路径
"coverOld": true, //是否覆盖旧的文件，主要用于mardown文件覆盖
"createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
"packageFilters": "",//controller包过滤，多个包用英文逗号隔开，2.2.2开始需要采用正则：com.test.controller.*
"md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
"style":"xt256", //基于highlight.js的代码高设置,可选值很多可查看码云wiki，喜欢配色统一简洁的同学可以不设置
"projectName": "smart-doc",//配置自己的项目名称，不设置则插件自动获取pom中的projectName
"framework": "spring",//smart-doc默认支持spring和dubbo框架的文档，使用默认框架不用配置，当前支持spring、dubbo、JAX-RS(待完善)
"skipTransientField": true,//目前未实现
"sortByTitle":false,//接口标题排序，默认为false,@since 1.8.7版本开始
"showAuthor":true,//是否显示接口作者名称，默认是true,不想显示可关闭
"requestFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
"responseFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@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":".do",//支持SpringMVC旧项目的url后缀,@since 2.1.0
"displayActualType":false,//配置true会在注释栏自动显示泛型的真实类型短类名，@since 1.9.6
"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配置接口服务地址
"tornaDebug":false,//启用会推送日志
"ignoreRequestParams":[ //忽略请求参数对象，把不想生成文档的参数对象屏蔽掉，@since 1.9.2
"org.springframework.ui.ModelMap"
],
"dataDictionaries": [{ //配置数据字典，没有需求可以不设置
"title": "http状态码字典", //数据字典的名称
"enumClassName": "com.power.common.enums.HttpCodeEnum", //数据字典枚举类名称
"codeField": "code",//数据字典字典码对应的字段名称
"descField": "message"//数据字典对象的描述信息字典
}],
"errorCodeDictionaries": [{ //错误码列表，没有需求可以不设置
"title": "title",
"enumClassName": "com.power.common.enums.HttpCodeEnum", //错误码枚举类
"codeField": "code",//错误码的code码字段名称
"descField": "message"//错误码的描述信息对应的字段名
}],
"revisionLogs": [{ //文档变更记录，非必须
"version": "1.0", //文档版本号
"revisionTime": "2020-12-31 10:30", //文档修订时间
"status": "update", //变更操作状态，一般为：创建、更新等
"author": "author", //文档变更作者
"remarks": "desc" //变更描述
}
],
"customResponseFields": [{ //自定义添加字段和注释，一般用户处理第三方jar包库，非必须
"name": "code",//覆盖响应码字段
"desc": "响应代码",//覆盖响应码的字段注释
"ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注释的类名
"ignore":true, //设置true会被自动忽略掉不会出现在文档中
"value": "00000"//设置响应码的值
}],
"customRequestFields": [{ //自定义请求体的注释，@since 2.1.3，非必须
"name":"code", //属性名
"desc":"状态码", //描述
"ownerClassName":"com.xxx.constant.entity.Result", //属性对应的类全路径
"value":"200", //默认值或者mock值
"required":true, //是否必填
"ignore":false //是否忽略
}],
"requestHeaders": [{ //设置请求头，没有需求可以不设置
"name": "token",//请求头名称
"type": "string",//请求头类型
"desc": "desc",//请求头描述信息
"value":"token请求头的值",//不设置默认null
"required": false,//是否必须
"since": "-",//什么版本添加的改请求头
"pathPatterns": "/app/test/**",//请看https://smart-doc-group.github.io/#/zh-cn/diy/advancedFeatures?id=公共请求头
"excludePathPatterns":"/app/page/**"//请看https://smart-doc-group.github.io/#/zh-cn/diy/advancedFeatures?id=公共请求头
},{
"name": "appkey",//请求头
"type": "string",//请求头类型
"desc": "desc",//请求头描述信息
"value":"appkey请求头的值",//不设置默认null
"required": false,//是否必须
"pathPatterns": "/test/add,/testConstants/1.0",//正则表达式过滤请求头,url匹配上才会添加该请求头，多个正则用分号隔开
"since": "-"//什么版本添加的改请求头
}],
"requestParams": [ //公共请求参数(通过拦截器处理的场景)，@since 2.2.3,没有需求请不要设置
{
"name": "configPathParam",//请求参数名称
"type": "string",//请求参数类型
"desc": "desc",//请求参数描述信息
"paramIn": "path",
"value":"testPath",//不设置默认null
"required": false,//是否必须
"since": "-",//什么版本添加的改请求参数
"pathPatterns": "*",//正则表达式过滤请求参数
"excludePathPatterns":"/app/page/**" //参考请求头中的用法
},
{
"name": "configQueryParam",//请求参数名称
"type": "string",//请求参数类型
"desc": "desc",//请求参数描述信息
"paramIn": "query",
"value":"testQuery",//不设置默认null
"required": false,//是否必须
"since": "-",//什么版本添加的改请求参数
"pathPatterns": "*",//正则表达式过滤请求参数
"excludePathPatterns":"/app/page/**"
}
],
"rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖，配置后输出到文档方便使用者集成
"artifactId":"SpringBoot2-Dubbo-Api",
"groupId":"com.demo",
"version":"1.0.0"
}],
"rpcConsumerConfig": "src/main/resources/consumer-example.conf",//文档中添加dubbo consumer集成配置，用于方便集成方可以快速集成
"apiObjectReplacements": [{ // 自smart-doc 1.8.5开始你可以使用自定义类覆盖其他类做文档渲染，非必须
"className": "org.springframework.data.domain.Pageable",
"replacementClassName": "com.power.doc.model.PageRequestDto" //自定义的PageRequestDto替换Pageable做文档渲染
}],
"apiConstants": [{//从1.8.9开始配置自己的常量类，smart-doc在解析到常量时自动替换为具体的值，非必须
"constantsClassName": "com.power.doc.constants.RequestParamConstant"
}],
"responseBodyAdvice":{ //自smart-doc 1.9.8起，非必须项，ResponseBodyAdvice统一返回设置(不要随便配置根据项目的技术来配置)，可用ignoreResponseBodyAdvice tag来忽略
"className":"com.power.common.model.CommonResult" //通用响应体
},
"requestBodyAdvice":{ 自smart-doc 2.1.4 起，支持设置RequestBodyAdvice统一请求包装类，非必须
"className":"com.power.common.model.CommonResult"
},
"groups": [ // @since 2.2.5, 对不同的controller进行分组
{
"name": "测试分组",
"apis": "com.power.doc.controller.app.*"
}
],
"requestParamsTable": true, // 是否将请求参数表展示在文档中，默认true，@since 2.2.5
"responseParamsTable": true //是否将响应参数表展示在文档中, 默认true，@since 2.2.5
}
三：生成文档
至此，我们就可以生成文档了，当然，这部分需要你合规的编写注释才可以生成。
我得注释是这么写的：
/**
* 提交评论
* @param article_id 文章id
* @param email 邮箱
* @param content 评论内容
* @param content_reply 回复内容
* @param replyid 回复评论id
* @param request 请求对象
* @return json对象
* @throws Exception
*/
生成文档也很简单，如下图所示：
一般都是生成html，直接在浏览器中能打开。
生成的文档如下图所示：
这个文档生成插件还是很完美的。
四：多模块项目生成文档
项目结构如下图所示：
上面的maven结构假设是严格按照父子级来配置的，然后web1和web2都依赖于common，
这种情况下如果跑到web1下或者web2目录下直接执行mvn命令来编译都是无法完成的。需要在根目录上去执行命令编译命令才能通过，而smart-doc插件会通过类加载器去加载用户配置的一些类，因此是需要调用编译的和执行命令是一样的。这种情况下建议你建smart-doc-maven-plugin放到根pom.xml中，在web1和web2中放置各自的smart-doc.json配置。
然后通过-pl去指定让smart-doc生成指定 模块的文档。
操作命令如下：
生成web1模块的api文档
mvn smart-doc:markdown -Dfile.encoding=UTF-8 -pl :web1 -am
生成web2模块的api文档
mvn smart-doc:markdown -Dfile.encoding=UTF-8 -pl :web2 -am
就是在每个子模块中依次使用maven构建插件就可以了，很简单，这里注意：每个子模块都需要配置smart-doc.json文件。
放在包含controller的子模块
通过插件调用，需要在顶级pom下执行 mvn clean install，不然直接执行插件可能会报错。（基于注释生成需要有源码（xxx-resource.jar）包）
五：标签使用
Smart-doc为我们提供了很多的注释标签，具体请移步官方文档：
smart-doc-group.github.io/guide/guide
以上大概就是springboot集成smart-doc的基本过程。
有好的建议，请在下方输入你的评论。
