一.为什么要引入smart-doc?

1.非侵入式生成接口文档
2.减少接口文档的手动更新麻烦&保证了接口文档和代码的一致
3.随时可生成最新的接口文档
4.保持团队代码风格一致:smart-doc支持javadoc，必须按照这个才能生成有注释的接口文档

二.对比swagger

小结：
swagger
侵入式接口文档生成
每个接口及每个实体类都需要添加注解
配置复杂，需要添加依赖然后需要添加相关配置
编译后自动生成接口文档
需要启动后才能查看，如果配置了安全框架还需要开放相关接口

smart doc
非侵入式接口文档生成
需要按照java文档注释规范对接口及相关对象添加注释
编译文件后需要手动运行插件生成接口文档
配置简单，只需要引入插件，配置文档输出位置即可。相关更加复杂的配置根据需要自行配置。
无需启动项目，生成文档后可直接浏览

smart-doc主要是基于源代码和JAVADOC标注注释来生成文档，是在开发期或者是项目的编译期执行生成文档，在最终在打包运行的jar内你是找不到smart-doc的依赖的，因此是完全不侵入项目运行期的，也就不能像swagger一样项目启动时更新文档。

swagger主要原理是利用JAVA的注解和反射机制去生成文档。如果项目文档要比较清晰就必须使用大量的注解。注解和业务代码强绑定，当然最终构建产出的部署包里也就必须包含swagger的依赖了。也因为swagger是利用反射来生成文档，所以可以做到项目启动时更新文档

三.使用

1.引入jar包;

          <plugin><groupId>com.github.shalousun</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>2.2.7</version><configuration><configFile>./src/main/resources/smart-doc.json</configFile><projectName>Smart-Doc初体验</projectName></configuration></plugin>

配置smart-doc.json

{"serverUrl": "http://localhost:17150","outPath": "src/main/resources/static/doc","isStrict": false,"#####": "allInOne:true  此参数表示记录文档变更的记录","createDebugPage": false,"packageFilters": "com.it.zqm.controller.*","style":"xt256","showAuthor":true,"inlineEnum": true,"revisionLogs": [{"version": "文档版本号","version": "1.0","_revisionTime": "文档修订时间","revisionTime": "2020-12-31 10:30","_status": "update,create可选","status": "update","author": "author","_remarks": "变更描述","remarks": "desc"}],"errorCodeDictionaries": [{ //错误码列表，没有需求可以不设置"title": "title","enumClassName": "com.it.zqm.enums.ResultCodeEnum", //错误码枚举类"codeField": "code",//错误码的code码字段名称"descField": "message"//错误码的描述信息对应的字段名}]
}

这是一个最简单的配置smart-doc.json

 {"outPath": "D://md2"
}

1.支持javadoc，@param @apiNote @deprecated等
2.smart-doc自定义注释tag
@ignore ignore tag用于过滤请求参数对象上的某个字段，设置后smart-doc不输出改字段到请求参数列表中。关于响应字段忽略的请看【忽略响应字段】，如果ignore加到方法上，则接口方法不会输出到文档。
@required 如果你没有使用JSR303参数验证规范实现的方式来标注字段，就可以使用@required去标注请求参数对象的字段，标注smart-doc在输出参数列表时会设置为true。建议使用validation-api注解
@mock mock tag用于在对象基本类型字段设置自定义文档展示值。设置值后smart-doc不再帮你生成随机值。方便可以通过smart-doc直接输出交付文档。

泛型使用规约:
T: Type（Java 类）通用泛型类型，通常作为第一个泛型类型
S: 通用泛型类型，如果需要使用多个泛型类型，可以将S作为第二个泛型类型
U: 通用泛型类型，如果需要使用多个泛型类型，可以将U作为第三个泛型类型
V: 通用泛型类型，如果需要使用多个泛型类型，可以将V作为第四个泛型类型
E: 集合元素泛型类型，主要用于定义集合泛型类型
K: 映射-键泛型类型，主要用于定义映射泛型类型
V: 映射-值泛型类型，主要用于定义映射泛型类型
N: Number数值泛型类型，主要用于定义数值类型的泛型类型
?: 表示不确定的java类型

注意:统一出参使用泛型的使用，在生成文档时接口需指定泛型的具体结构，生成文档后恢复。

3.支持html，markdown等格式，还可以生成postman文档。

四.讨论

1.设计先行模式

由比较有经验的人编写设计文档和接口协议。
完成设计后主要由业务开发工程师根据设计文档开发业务逻辑。
架构师也可以像国外一些架构师一下，直接定义好程序的接口框架，然后交付给业务工程师填充业务代码。
设计先行通常在成熟的开发团队中。在代码先行模式下，接口协议虽然在设计阶段都已经定义好。但是smart-doc仍然很有用。
设计的好的接口协议后期的持续更新遗漏，仍然是个问题，人性本是懒惰的。smart-doc能够保持文档和代码的一致性。
一个新成员进入团队看代码，html的文档明面比word写的更方便跟踪。新成员完全可以直接上手打开debug文档页面调试熟悉业务。
smart-doc由于采用源码分析，对代码的标准度要求高于其他工具，使用这个工具直接就能统一团队风格。
还可以基于smart-doc定制开发，将文档输送到yapi这样类似的接口文档管理中。
目前国内主流的设计先行的文档方式，主要就是word或者是markdown。word的翻页对接口展示很不友好。

2.代码先行

代码先行的这种模式，利用smart-doc天然就可以一边写代码一边出接口文档。然后利用smart-doc对代码的规范要求严格度。完全可以保证团队代码风格不会出现很大差异。

代码先行在很多团队是有弊端的，代码先行特别是对大型系统，对代码编写者能力要求很高。代码和业务的结合能力需要非常强，能够考虑到扩展和业务边界。代码先行这种，也可以走另外一种路线，团队的架构师直接搭建好项目框架后，定义好接口框架代码，填充业务逻辑部分全部空出来。有了接口，smart-doc已经可以扫描生成接口文档了

五.体验

1.依赖

2.生成文档

六.附录

1.完整的配置项:

{"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、solon "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"requestParamsTable": true, //@since 2.2.5,是否在文档中显示请求参数表，默认值为 true。"responseParamsTable": true, //@since 2.2.5,是否在文档中显示返回参数表，默认值为 true。"urlSuffix":".do",//支持SpringMVC旧项目的url后缀,@since 2.1.0"displayActualType":false,//配置true会在注释栏自动显示泛型的真实类型短类名，"appToken": "c16931fa6590483fb7a4e85340fcbfef", //torna平台appToken,@since 2.0.9"isReplace":true, //torna 是否覆盖历史推送 @since 2.2.4"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": [{//smart-doc在解析到常量时自动替换为具体的值，非必须，2.4.2开始不用配置，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
}

2.官方地址:

链接: smart-doc官方文档.

smart-doc初体验-springboot生成自动文档相关推荐

springboot生成接口文档
当我们在使用Spring MVC写接口的时候,为了生成API文档,为了方便整合Swagger,都是用这个SpringFox的这套封装.但是,自从2.9.2版本更新之后,就一直没有什么动静,也没有更上S ...
可以生成自动文档的注释
使用/**和*/可以用来自动的生成文档. 这种注释以/**开头,以*/结尾
springboot 生成pdf文档
Document document = new Document(PageSize.A4); try { String fileName = "bb.pdf"; response. ...
Sphinx——自动生成Python文档
Sphinx是一个可自动生成python项目api的工具,使用起来也比较简单,只需要在项目上进行简单的配置,即可生成项目的api文档简介 Sphinx是Python文档生成器,它基于reStruct ...
springboot 中文文档_比Swagger还好用的自动生成接口文档工具
JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后 ...
springboot 集成 swagger 自动生成API文档
Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案. S ...
springboot api文档_SpringCloud/SpringBoot - 自动生成API文档
SpringCloud/SpringBoot 的项目一定要前后分离,这就需要一个API文档生成的工具,后端一定要和前端或者是移动端对接接口,那么问题来了,接口是不是要自己写给他们看,一般的会采用Exc ...
springboot 之自动生成接口文档工具JApiDocs
JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具简易使用方法 1.添加依赖 <dependency><groupId>io.github.y ...
SpringBoot 自动生成API文档
SpringBoot 自动生成API文档在做项目的时候,如果项目是前后分离的,后端一定要和前端或者是移动端对接接口,那么问题来了,接口是不是要自己写给他们看,一般的会采用Excel或者Word来写, ...

smart-doc初体验-springboot生成自动文档

smart-doc初体验