零注解侵入的API接口文档生成插件——Smart-doc
smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具，在业内率先提出基于JAVA泛型定义推导的理念， 完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。 你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。
1 特性
- 零注解、零学习成本、只需要写标准
JAVA注释。 - 基于源代码接口定义自动推导，强大的返回结构推导。
- 支持
Spring MVC、Spring Boot、Spring Boot Web Flux(Controller书写方式)、Feign。 - 支持
Callable、Future、CompletableFuture等异步接口返回的推导。 - 支持
JavaBean上的JSR303参数校验规范，包括分组验证。 - 对
JSON请求参数的接口能够自动生成模拟JSON参数。 - 对一些常用字段定义能够生成有效的模拟值。
- 支持生成
JSON返回值示例。 - 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
- 支持生成多种格式文档：
Markdown、HTML5、Word、Asciidoctor、Postman Collection、OpenAPI 3.0。 开放文档数据，可自由实现接入文档管理系统。 - 支持导出错误码和定义在代码中的各种字典码到接口文档。
- 支持生成
JMeter性能测试脚本。 - 支持
Maven、Gradle插件式轻松集成。 - 支持
Apache Dubbo RPC接口文档生成。 - 支持普通
Java类生成javadoc文档。 - 支持基于
Git管理项目的变更增量文档生成。 debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。
2 与Swagger对比
| 功能特性 | smart-doc | swagger |
|---|---|---|
| 代码侵入 | 无 | 注解侵入性严重 |
| 集成复杂度 | 简单，只需插件 | 偏复杂 |
| 插件支持 | 有 gradle 和 maven 插件 | 无插件 |
| openapi 规范支持 | 支持 openapi 3.0 | 完全支持 openapi 的版本 |
| CI 构建集成 | 可在 ci 构建阶段使用maven 或者 gradle 命令启动插件生成文档 | 不支持 |
| 集中化文档中心集成 | 已经和 torna 企业级接口文档管理平台对接 | 不支持 |
| 维护持续性 | 值得信赖，开源后用户基础多，一直持续维护 | 全球用户多，开源维护值得信赖 |
| 接口 debug | 2.0.0 版本开始已经支持 debug，页面比 swagger 漂亮太多了。 | 支持 |
Smart-doc 从 2.0.0 后几乎实现了 swagger ui 的功能，并且比 swagger ui 更简洁大方，也更符合国内开发者的诉求。当然 smart-doc 的功能也已经超过了 swagger 为 java 开发者提供的功能。当然 smart-doc 本身是只支持扫描代码生成 openapi 3.0 的文档的，也可以将生成的 openapi 3.0 文档导入到其他 ui 中渲染展示。
设计思路不同，smart-doc 是基于 源码分析的，它生成api文档是通过分析JAVA源码主要是通过 注释 和 系统自带注解，来实现文档的 生成，而 swagger 是运行时自动生成在线文档，并且生成测试接口的案例。由于他们设计思路不一样，swagger2 使用过程需要使用它定义的 @API 相关注解，这样就污染了源码，代码入侵有点高，而smart -doc 不同，主要是通过注释来生成API文档的 。
与 Swagger 对比最大的区别在于：
- Smart-doc 不需要启动，直接运行插件就可以生成api文档；
- Smart-doc 不需要编写复杂注解来生成文档；
3 使用和实践
3.1 引入maven依赖
<build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin><plugin><groupId>com.github.shalousun</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>2.4.8</version><configuration><!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--><configFile>./src/main/resources/smart-doc.json</configFile><!--指定项目名称，推荐使用动态参数，例如${project.description}--><!--如果smart-doc.json中和此处都未设置projectName，2.3.4开始，插件自动采用pom中的projectName作为设置--><projectName>${project.description}</projectName></configuration><executions><execution><!--如果不需要在执行编译时启动smart-doc，则将phase注释掉--><phase>compile</phase><goals><!--smart-doc提供了html、openapi、markdown等goal，可按需配置--><goal>html</goal></goals></execution></executions></plugin></plugins></build>
3.2 配置 Smart-doc 插件
结合我司实际使用情况来看，我们采用的是Smart-doc + Apifox 来生成、解析接口文档进行前后端协作开发。在resource下创建一个smart-doc.json文件，内容如下：
{"serverUrl": "http://123.xxx.xxx.165:18888","pathPrefix": "/api/v1","isStrict": false,"allInOne": true,"nameStyle": "original","outPath": "src/main/resources/templates/apidoc","coverOld": true,"createDebugPage": true,"packageFilters": "com.xxx.insurance.agency.app.controller.temp.*","md5EncryptedHtmlName": false,"style": "xt256","projectName": "xxx App-Console API","skipTransientField": true,"sortByTitle": false,"showAuthor": true,"requestFieldToUnderline": false,"responseFieldToUnderline": false,"inlineEnum": true,"recursionLimit": 7,"allInOneDocFileName": "index.html","requestExample": "true","responseExample": "true","version": "v0.0.1","responseBodyAdvice": {"className": "com.xxx.ddd.base.CommonResponse"},"requestHeaders": [{"name": "X-xxx-Webservice-Id","type": "string","desc": "请求特有的webServiceId","value": "xxx","required": true},{"name": "Authorization","type": "string","desc": "Bearer开头的登陆校验","value":"Bearer ","required": true}]
}
介绍一些重要的配置参数，其中:
-
outPath表示api文档输出路径; -
serverUrl表示服务url，便于前端发起请求联调； -
pathPrefix表示路径前缀，注意在Controller层无需重复写requestMapping的前缀； -
packageFilters表示仅检测该包路径下的Controller类； -
requestHeaders表示自动添加的请求头; -
responseBodyAdvice表示为我们自动增强的切面类;其他参数以及更多参数介绍请参考官网：https://smart-doc-group.github.io/zh/
3.3 使用maven插件生成api文档
也可以使用maven命令生成：
// Http Restful api文档
//生成 html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成 markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//生成 adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成 postman json数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman
// 生成 OpenApi 3.0
mvn -Dfile.encoding=UTF-8 smart-doc:openapi// Apache Dubbo RPC文档
// 生成 html
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
// 生成 markdown
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
// 生成 adoc
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc
生成后如下图所示：
3.4 实践效果
如果采用postman管理api接口，可以生成postman的json格式的文档，如果使用apifox可以生成markdown或openapi导入，导入api文档后如下图所示：
生成的html文档如下所示：
以上。
本博客内容仅供个人学习使用，禁止用于商业用途。转载需注明出处并链接至原文。
