使⽤smart-doc⾃动⽣成接⼝⽂档，解放java开发者
⽬录
1、接⼝⽂档⾯对的困境
我⼯作⼏年，接⼝⽂档⽤过好⼏种⽅式了。从最开始的word⽂档，到后来的swagger和confluence编写接⼝⽂档，再到后来侵⼊性很⼩的jApiDoc，最后到现在的smart-doc⼯具。
对⽐下他们的优缺点：
⽅式好处缺点
word⽂档和
confluence
有⽂档留存（好像也不算好处）费时费⼒、多⼈编写不便
swagger 1、不⽤专门写⽂档
postman在线测试2、通过连接直接访问
3、在线测试，有点像简化的postman
注释太多，写的想打⼈
jApiDoc 1、引⼊jar包，⼀键⽣成html接⼝⽂档
2、侵⼊⼩，添加简单注释就⾏
1、功能单⼀，只能接
⼝⽂档
2、作者好久没有维护
了
smart-doc 1、引⼊maven插件，⼀键⽣成HTML接⼝⽂档
2、作者很活跃，社区也很活跃，反应问题很快就
有新版本解决
3、能⽣成常⽤的html，markdown、postman接
⼝⽂档
4、侵⼊⼩，添加简单注释就⾏
5、适配单服务、微服务等多种环境
1、需要抽两个⼩时看下官
⽅⽂档
2、JApiDocs简介
前⾯我介绍过⼀种⼯具，叫做JApiDocs，这个⼯具我也使⽤了⼀段时间，⽤起来还是不错的，能满⾜基本要求，
3、前⾔
被写接⼝⽂档难受了好久，使⽤swagger要加各种稀奇古怪的注释，⼗分繁琐，突然看到JApiDocs 的介绍，只需要在接⼝上加上点注释，就能够⽣成接⼝⽂档。突然来了希望，通过看⽂档⾃⼰使⽤之后，
把踩过的坑记录下来
⽣成的接⼝⽂档页⾯展⽰：
查询接⼝
新增接⼝
删除接⼝
官⽅说明⽂档：
⽂档内容，说明、使⽤范⽂很齐全，特别适合我们使⽤，我会举个例⼦，⼤家如果要使⽤的话，还是抽⼀两个⼩时看看官⽅⽂档，会有很⼤帮助，⽂档地址如下：
4、快速使⽤
添加插件
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.0.8</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⽀持，配置了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>
在Resources下新增⼀个接⼝⽂档配置⽂件
看着配置很多，⼤部分时候我们使⽤默认配置就⾏了，并且每个配置作者都给加好了注释，⼀看就懂了
⽂档内容如下
{
"serverUrl": "127.0.0.1:8072/test", //设置服务器地址,⾮必须
"isStrict": false, //是否开启严格模式
"allInOne": true,  //是否将⽂档合并到⼀个⽂件中，⼀般推荐为true
"outPath": "src/main/resources/static/doc", //指定⽂档的输出路径
"coverOld": true,  //是否覆盖旧的⽂件，主要⽤于mardown⽂件覆盖
"packageFilters": "",//controller包过滤，多个包⽤英⽂逗号隔开
"style":"xt256", //基于highlight.js的代码⾼亮设置，喜欢配⾊统⼀简洁的同学可以不设置
"createDebugPage": true,//@since 2.0.0 smart-doc⽀持创建可以测试的html页⾯，仅在AllInOne模式中起作⽤。
"md5EncryptedHtmlName": false,//只有每个controller⽣成⼀个html⽂件是才使⽤
"projectName": "这⾥修改项⽬名",//配置⾃⼰的项⽬名称
"skipTransientField": true,//⽬前未实现
"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版本开始
"displayActualType":false,//配置true会在注释栏⾃动显⽰泛型的真实类型短类名，@since 1.9.6
"ignoreRequestParams":[ //忽略请求参数对象，把不想⽣成⽂档的参数对象屏蔽掉，@since 1.9.2
"org.springframework.ui.ModelMap"
],
"dataDictionaries": [ //配置数据字典，没有需求可以不设置
{
"title": "http状态码字典", //数据字典的名称
"enumClassName": "ums.HttpCodeEnum", //数据字典枚举类名称
"codeField": "code",//数据字典字典码对应的字段名称
"descField": "message"//数据字典对象的描述信息字典
}
],
"errorCodeDictionaries": [{ //错误码列表，没有需求可以不设置
"title": "title",
"enumClassName": "ums.HttpCodeEnum", //错误码枚举类，如果是枚举是在⼀个类中定义则⽤$链接类BaseErrorCode$Common
"codeField": "code",//错误码的code码字段名称
"descField": "message"//错误码的描述信息对应的字段名
}],
"revisionLogs": [ //设置⽂档变更记录，没有需求可以不设置
{
"version": "1.0", //⽂档版本号
"status": "update", //变更操作状态，⼀般为：创建、更新等
"author": "author", //⽂档变更作者
"remarks": "desc" //变更描述
},
{
"version": "1.0", //⽂档版本号
"status": "update", //变更操作状态，⼀般为：创建、更新等
"author": "author", //⽂档变更作者
"remarks": "desc" //变更描述
}
],
"customResponseFields": [ //⾃定义添加字段和注释，api-doc后期遇到同名字段则直接给相应字段加注释，⾮必须
{
"name": "code",//覆盖响应码字段
"desc": "响应代码",//覆盖响应码的字段注释
"ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注释的类名
"value": "00000"//设置响应码的值
}
],
"requestHeaders": [ //设置请求头，没有需求可以不设置
{
"name": "Authorization",
"type": "string",
"desc": "desc",
"required": false,
"value":"Bearer ebb616e4-b23f-4b60-b9dc-f8393393bd39",
"since": "-"
}
]
,
"rpcApiDependencies":[{ // 项⽬开放的dubbo api接⼝模块依赖，配置后输出到⽂档⽅便使⽤者集成
"artifactId":"SpringBoot2-Dubbo-Api",
"groupId":"com.fj",
"version":"1.0.0"
}],
"rpcConsumerConfig":"src/main/f",//⽂档中添加dubbo consumer集成配置，⽤于⽅便集成⽅可以快速集成
"apiObjectReplacements": [{ // ⾃smart-doc 1.8.5开始你可以使⽤⾃定义类覆盖其他类做⽂档渲染，使⽤全类名
"className": "org.springframework.data.domain.Pageable",
"replacementClassName": "com.del.PageRequestDto" //⾃定义的PageRequestDto替
换Pageable做⽂档渲染
}]//,
//  "apiConstants": [{//从1.8.9开始配置⾃⼰的常量类，smart-doc在解析到常量时⾃动替换为具体的值，如：localhost:8080/testConstants/+ApiVersion.VERSION

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。