一直使用swagger进行接口文档管理，但是只能通过服务下的html访问，且注解对代码有侵入。在前后端联调时也不太方便管理和进一步修改。
反之smartdoc有以下优点：无侵入，不用写注解，只用写方法和类属性注释。可以生成html postman matkdown 文档。支持在线调试，文档结构简洁明了。可以对生成文档进行二次加工和部署。
一、在springboot项目pom.xml中添加plugin
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.6.7</version>
<configuration>
<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>测试</projectName>
<!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
<excludes>
<!--格式为：groupId:artifactId;参考如下-->
<!--也可以支持正则式如：com.alibaba:.* -->
<exclude>com.alibaba:fastjson</exclude>
</excludes>
<!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有，因此使用时需要注意-->
<!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
<includes>
<!--格式为：groupId:artifactId;参考如下-->
<!--也可以支持正则式如：com.alibaba:.* -->
<!-- 使用了mybatis-plus的Page分页需要include所使用的源码包 -->
<include>com.baomidou:mybatis-plus-extension</include>
<include>com.iflytek.note:common-base</include>
<!-- 使用了mybatis-plus的IPage分页需要include mybatis-plus-core-->
<include>com.baomidou:mybatis-plus-core</include>
<!-- 如果配置了includes的情况下， 使用了jpa的分页需要include所使用的源码包 -->
<include>org.springframework.data:spring-data-commons</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>
如果请求体、返回体依赖三方jar包，需要在
二、在resources下创建smart-doc.json
{
"outPath": "doc/",
"serverUrl": "http://localhost:8079/",
"createDebugPage": true,
"projectName": "xxxx",
"pathPrefix": "",
"isStrict": false,
"allInOne": true,
"coverOld": true,
"createDebugPage": true,
"packageFilters": "",
"md5EncryptedHtmlName": false,
"style":"xt256",
"projectName": "smart-doc",
"skipTransientField": true,
"sortByTitle":false,
"showAuthor":true,
"requestFieldToUnderline":true,
"responseFieldToUnderline":true,
"inlineEnum":true,
"recursionLimit":7,
"allInOneDocFileName":"index.html",
"requestExample":"true",
"responseExample":"true",
"requestParamsTable": true,
"responseParamsTable": true,
"displayActualType":false,
"appKey": "20201216788835306945118208",
"appToken": "c16931fa6590483fb7a4e85340fcbfef",
"secret": "W.ZyGMOB9Q0UqujVxnfi@.I#V&tUUYZR",
"debugEnvName":"测试环境",
"tornaDebug":false,
"ignoreRequestParams":[
"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",
"descField": "message"
}],
"revisionLogs": [{
"version": "1.0",
"revisionTime": "2020-12-31 10:30",
"status": "update",
"author": "author",
"remarks": "desc"
}
],
"customResponseFields": [{
"name": "code",
"desc": "响应代码",
"ownerClassName": "org.springframework.data.domain.Pageable",
"ignore":true,
"value": "00000"
}],
"customRequestFields": [{
"name":"code",
"desc":"状态码",
"ownerClassName":"com.xxx.constant.entity.Result",
"value":"200",
"required":true,
"ignore":false
}],
"requestHeaders": [{
"name": "token",
"type": "string",
"desc": "desc",
"value":"token请求头的值",
"required": false,
"since": "-",
"pathPatterns": "/app/test/**",
"excludePathPatterns":"/app/page/**"
},{
"name": "appkey",
"type": "string",
"desc": "desc",
"value":"appkey请求头的值",
"required": false,
"pathPatterns": "/test/add,/testConstants/1.0",
"since": "-"
}],
"requestParams": [
{
"name": "configPathParam",
"type": "string",
"desc": "desc",
"paramIn": "path",
"value":"testPath",
"required": false,
"since": "-",
"pathPatterns": "*",
"excludePathPatterns":"/app/page/**"
},
{
"name": "configQueryParam",
"type": "string",
"desc": "desc",
"paramIn": "query",
"value":"testQuery",
"required": false,
"since": "-",
"pathPatterns": "*",
"excludePathPatterns":"/app/page/**"
}
],
"rpcConsumerConfig": "src/main/resources/consumer-example.conf",
"apiObjectReplacements": [{
"className": "org.springframework.data.domain.Pageable",
"replacementClassName": "com.power.doc.model.PageRequestDto"
}],
"groups": [
{
"name": "测试分组",
"apis": "com.power.doc.controller.app.*"
}
]
}
三、创建接口
/**
* 内部测试接口
*/
@RestController
@RequestMapping("/api")
//@EnableEurekaClient
public class TestController {
/**
* 测试接口2
* @param testParam
* @return
*/
@GetMapping( "/test2")
public RtData<TestParam> test2(TestParam testParam){
return ResponseBuilder.success(testParam);
}
}
四、生成html文档
终端执行命令
mvn -Dfile.encoding=UTF-8 smart-doc:html
打开index.htlm
五、支持swagger
pom.xml添加依赖
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.0</version>
</dependency>
执行命令，生成openapi.json
mvn -Dfile.encoding=UTF-8 smart-doc:swagger
将openapi.json文件拷贝到src/main/resources/static/doc文件夹下
application.json添加配置：
springdoc.swagger-ui.path=/swagger-ui-custom.html
springdoc.swagger-ui.operations-sorter=method
#custom path for api docs
springdoc.swagger-ui.url=/doc/openapi.json
启动项目，打开地址：http://localhost:8079/swagger-ui-custom.html
六、其他功能支持
支持导出html postman markdown等格式文件。
更多内容参考：
https://smart-doc-group.github.io/#/zh-cn/start/quickstart