在maven中添加smart-doc 插件
smart-doc是一款API文档生成工具，无需多余操作，只要你规范地写好代码注释，就能生成API文档。同时能直接生成Postman调试文件，一键导入Postman即可调试，非常好用！

添加

smart-doc官方目前已经开发完成Maven插件 和Gradle插件，
你可以根据自己的构建工具来选择使用Maven插件或者是Gradle插件。

maven 地址：https://mvnrepository.com/artifact/com.github.shalousun/smart-doc-maven-plugin

  2. <plugin>
  3.     <groupId>com.github.shalousun</groupId>
  4.     <artifactId>smart-doc-maven-plugin</artifactId>
  5.     <version>2.2.9</version>
  6.     <configuration>
  7.         <!--指定smart-doc使用的配置文件路径-->
  8.         <configFile>./src/main/resources/smart-doc.json</configFile>
  9.         <!--指定项目名称-->
  10.         <projectName>mall-tiny-smart-doc</projectName>
  11.     </configuration>
  12.     <executions>
  13.         <execution>
  14.             <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
  15.             <phase>compile</phase>
  16.             <goals>
  17.                 <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
  18.                 <goal>html</goal>
  19.             </goals>
  20.         </execution>
  21.     </executions>
  22. </plugin>

配置文件

在项目中添加创建一个smart-doc.json配置文件，插件读取这个配置来生成项目的文档

最小配置

  1. {
  2.    "outPath": "D://md2" //指定文档的输出路径,相对路径时请用./开头，eg:./src/main/resources/static/doc
  3. }

完整配置

  1. {
  2.   "serverUrl": "http://127.0.0.1", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
  3.   "pathPrefix": "", //设置path前缀,非必须。如配置Servlet ContextPath 。@since 2.2.3
  4.   "isStrict": false, //是否开启严格模式
  5.   "allInOne": true,  //是否将文档合并到一个文件中，一般推荐为true
  6.   "outPath": "D://md2", //指定文档的输出路径
  7.   "coverOld": true,  //是否覆盖旧的文件，主要用于mardown文件覆盖
  8.   "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
  9.   "packageFilters": "",//controller包过滤，多个包用英文逗号隔开，2.2.2开始需要采用正则：com.test.controller.*
  10.   "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件时才使用
  11.   "style":"xt256", //基于highlight.js的代码高设置,可选值很多可查看码云wiki，喜欢配色统一简洁的同学可以不设置
  12.   "projectName": "smart-doc",//配置自己的项目名称
  13.   "skipTransientField": true,//目前未实现
  14.   "sortByTitle":false,//接口标题排序，默认为false,@since 1.8.7版本开始
  15.   "showAuthor":true,//是否显示接口作者名称，默认是true,不想显示可关闭
  16.   "requestFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  17.   "responseFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  18.   "inlineEnum":true,//设置为true会将枚举详情展示到参数表中，默认关闭，//@since 1.8.8版本开始
  19.   "recursionLimit":7,//设置允许递归执行的次数用于避免一些对象解析卡住，默认是7，正常为3次以内，//@since 1.8.8版本开始
  20.   "allInOneDocFileName":"index.html",//自定义设置输出文档名称, @since 1.9.0
  21.   "requestExample":"true",//是否将请求示例展示在文档中，默认true，@since 1.9.0
  22.   "responseExample":"true",//是否将响应示例展示在文档中，默认为true，@since 1.9.0
  23.   "requestParamsTable": true, //是否将请求参数表展示在文档中，默认true，@since 2.2.5
  24.   "responseParamsTable": true //是否将响应参数表展示在文档中, 默认true，@since 2.2.5
  25.   "urlSuffix":".do",//支持SpringMVC旧项目的url后缀,@since 2.1.0
  26.   "displayActualType":false,//配置true会在注释栏自动显示泛型的真实类型短类名，@since 1.9.6
  27.   "appKey": "20201216788835306945118208",// torna平台对接appKey,, @since 2.0.9
  28.   "appToken": "c16931fa6590483fb7a4e85340fcbfef", //torna平台appToken,@since 2.0.9
  29.   "secret": "W.ZyGMOB9Q0UqujVxnfi@.I#V&tUUYZR",//torna平台secret，@since 2.0.9
  30.   "openUrl": "http://localhost:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
  31.   "debugEnvName":"测试环境", //torna环境名称
  32.   "debugEnvUrl":"http://127.0.0.1",//推送torna配置接口服务地址
  33.   "tornaDebug":false,//启用会推送日志
  34.   "replace":true, // 推送文档到torna强制替换 @since 2.2.4
  35.   "ignoreRequestParams":[ //忽略请求参数对象，把不想生成文档的参数对象屏蔽掉，@since 1.9.2
  36.      "org.springframework.ui.ModelMap"
  37.    ],
  38.   "dataDictionaries": [{ //配置数据字典，没有需求可以不设置
  39.       "title": "http状态码字典", //数据字典的名称
  40.       "enumClassName": "com.power.common.enums.HttpCodeEnum", //数据字典枚举类名称
  41.       "codeField": "code",//数据字典字典码对应的字段名称
  42.       "descField": "message"//数据字典对象的描述信息字典
  43.   }],
  44.   "errorCodeDictionaries": [{ //错误码列表，没有需求可以不设置
  45.     "title": "title",
  46.     "enumClassName": "com.power.common.enums.HttpCodeEnum", //错误码枚举类
  47.     "codeField": "code",//错误码的code码字段名称
  48.     "descField": "message"//错误码的描述信息对应的字段名
  49.   }],
  50.   "revisionLogs": [{ //文档变更记录，非必须
  51.       "version": "1.0", //文档版本号
  52.       "revisionTime": "2020-12-31 10:30", //文档修订时间
  53.       "status": "update", //变更操作状态，一般为：创建、更新等
  54.       "author": "author", //文档变更作者
  55.       "remarks": "desc" //变更描述
  56.     }
  57.   ],
  58.   "customResponseFields": [{ //自定义添加字段和注释，一般用户处理第三方jar包库，非必须
  59.       "name": "code",//覆盖响应码字段
  60.       "desc": "响应代码",//覆盖响应码的字段注释
  61.       "ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注释的类名
  62.       "ignore":true, //设置true会被自动忽略掉不会出现在文档中
  63.       "value": "00000"//设置响应码的值
  64.   }],
  65.   "customRequestFields": [{ //自定义请求体的注释，@since 2.1.3，非必须
  66.        "name":"code", //属性名
  67.        "desc":"状态码", //描述
  68.        "ownerClassName":"com.xxx.constant.entity.Result", //属性对应的类全路径
  69.        "value":"200", //默认值或者mock值
  70.        "required":true, //是否必填
  71.        "ignore":false //是否忽略
  72.   }],
  73.   "requestHeaders": [{ //设置请求头，没有需求可以不设置
  74.       "name": "token",//请求头名称
  75.       "type": "string",//请求头类型
  76.       "desc": "desc",//请求头描述信息
  77.       "value":"token请求头的值",//不设置默认null
  78.       "required": false,//是否必须
  79.       "since": "-",//什么版本添加的改请求头
  80.       "pathPatterns": "/app/test/**",//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
  81.       "excludePathPatterns":"/app/page/**"//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
  82.   },{
  83.       "name": "appkey",//请求头
  84.       "type": "string",//请求头类型
  85.       "desc": "desc",//请求头描述信息
  86.       "value":"appkey请求头的值",//不设置默认null
  87.       "required": false,//是否必须
  88.       "pathPatterns": "/test/add,/testConstants/1.0",//正则表达式过滤请求头,url匹配上才会添加该请求头，多个正则用分号隔开
  89.       "since": "-"//什么版本添加的改请求头
  90.   }],
  91.   "requestParams": [ //公共请求参数(通过拦截器处理的场景)，@since 2.2.3,没有需求请不要设置
  92.     {
  93.       "name": "configPathParam",//请求头名称
  94.       "type": "string",//请求头类型
  95.       "desc": "desc",//请求头描述信息
  96.       "paramIn": "path",
  97.       "value":"testPath",//不设置默认null
  98.       "required": false,//是否必须
  99.       "since": "-",//什么版本添加的改请求头
  100.       "pathPatterns": "*",//正则表达式过滤请求头
  101.       "excludePathPatterns":"/app/page/**" //参考请求头中的用法
  102.     },
  103.     {
  104.       "name": "configQueryParam",//请求头名称
  105.       "type": "string",//请求头类型
  106.       "desc": "desc",//请求头描述信息
  107.       "paramIn": "query",
  108.       "value":"testQuery",//不设置默认null
  109.       "required": false,//是否必须
  110.       "since": "-",//什么版本添加的改请求头
  111.       "pathPatterns": "*",//正则表达式过滤请求头
  112.       "excludePathPatterns":"/app/page/**"
  113.     }
  114.   ],
  115.   "rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖，配置后输出到文档方便使用者集成
  116.         "artifactId":"SpringBoot2-Dubbo-Api",
  117.         "groupId":"com.demo",
  118.         "version":"1.0.0"
  119.    }],
  120.   "rpcConsumerConfig": "src/main/resources/consumer-example.conf",//文档中添加dubbo consumer集成配置，用于方便集成方可以快速集成
  121.   "apiObjectReplacements": [{ // 自smart-doc 1.8.5开始你可以使用自定义类覆盖其他类做文档渲染，非必须
  122.       "className": "org.springframework.data.domain.Pageable",
  123.       "replacementClassName": "com.power.doc.model.PageRequestDto" //自定义的PageRequestDto替换Pageable做文档渲染
  124.   }],
  125.   "apiConstants": [{//从1.8.9开始配置自己的常量类，smart-doc在解析到常量时自动替换为具体的值，非必须
  126.         "constantsClassName": "com.power.doc.constants.RequestParamConstant" //引用常量时需要用RequestParamConstant.xxx才能被正确解析
  127.   }],
  128.   "responseBodyAdvice":{ //自smart-doc 1.9.8起，非必须项，ResponseBodyAdvice统一返回设置(不要随便配置根据项目的技术来配置)，可用ignoreResponseBodyAdvice tag来忽略
  129.           "className":"com.power.common.model.CommonResult" //通用响应体
  130.   },
  131.   "requestBodyAdvice":{ ////自smart-doc 2.1.4 起，支持设置RequestBodyAdvice统一请求包装类，非必须
  132.          "className":"com.power.common.model.CommonResult"
  133.   },
  134.   "groups": [ // @since 2.2.5, 对不同的controller进行分组
  135.     {
  136.       "name": "测试分组",
  137.       "apis": "com.power.doc.controller.app.*"
  138.     }
  139.   ]
  140. }

上面的JSON配置实例中只有”outPath”是必填项。其他额外配置项请根据实际情况来配置，请不要胡乱复制上面的全配置到自己的项目中 可能引起使用错误

推荐配置

  1. {
  2.   "serverUrl": "http://{{server}}:{{port}}", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
  3.   "pathPrefix": "", //设置path前缀,非必须。如配置Servlet ContextPath 。@since 2.2.3
  4.   "allInOne": true,  //是否将文档合并到一个文件中，一般推荐为true
  5.   "outPath": "D://smart-doc//walking-api", //指定文档的输出路径
  6.   "coverOld": true,  //是否覆盖旧的文件，主要用于mardown文件覆盖
  7.   "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
  8.   "projectName": "walking-api",//配置自己的项目名称
  9. }

命令生成

mvn命令生成

  1. //生成html
  2. mvn -Dfile.encoding=UTF-8 smart-doc:html
  3. //生成markdown
  4. mvn -Dfile.encoding=UTF-8 smart-doc:markdown
  5. //生成adoc
  6. mvn -Dfile.encoding=UTF-8 smart-doc:adoc
  7. //生成postman json数据
  8. mvn -Dfile.encoding=UTF-8 smart-doc:postman
  9. // 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
  10. mvn -Dfile.encoding=UTF-8 smart-doc:openapi
  11. // 生成文档推送到Torna平台
  12. mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest
  14. // Apache Dubbo RPC文档
  15. // Generate html
  16. mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
  17. // Generate markdown
  18. mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
  19. // Generate adoc
  20. mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc
  22. // 生成dubbo接口文档推送到torna
  23. mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc

自定义注解增强

参考：https://gitee.com/smart-doc-team/smart-doc/wikis/javadoc%20tag%E4%BD%BF%E7%94%A8/%E8%87%AA%E5%AE%9A%E4%B9%89tag%E4%BD%BF%E7%94%A8

多模块

多模块下具体情况具体分析
一般将该插件放在根pom中，在各个模块下配置各自的配置文件
使用命令进行生成

  1. mvn -X smart-doc:html -Dfile.encoding=UTF-8  -pl :《模块名》 -am

结论

只是适合单模块应用，对于复杂的多模块系统或者微服务完全不适合
增加学习成本，而且对于开发很不友好