SpringBoot 集成接口文档，老鸟们也被打脸了！

• …

接下来我们来看看SpringBoot中如何集成smart-doc。

SpringBoot集成 smart-doc

---

smart-doc支持多种方式生成接口文档：maven插件、gradle插件、单元测试（不推荐），这里我才用的是基于maven插件生成，步骤如下：

1. 引入依赖，版本选择最新版本

com.github.shalousun

smart-doc-maven-plugin

2.2.7

./src/main/resources/smart-doc.json

Smart-Doc初体验

重点在 configFile中指定smart-doc配置文件 smart-doc.json

2. 新建配置文件smart-doc.json

{

“outPath”: “src/main/resources/static/doc”

}

指定smart-doc生成的文档路径，其他配置项可以参考官方wiki。

3. 通过执行maven 命令生成对应的接口文档

//生成html

mvn -Dfile.encoding=UTF-8 smart-doc:html

当然也可以通过idea中的maven插件生成

4. 访问接口文档

生成接口文档后我们通过 http://localhost:8080/doc/api.html查看，效果如下：

看到这里的同学可能会呵呵一笑，就这？啥也没有呀！这还想让我替换Swagger？

别急，刚刚只是体验了smart-doc的基础功能，接下来我们通过丰富smart-doc的配置文件内容来增强其功能。

功能增强

---

1. 开启调试

一个优秀的接口文档工具调试功能必不能少，smart-doc支持在线调试功能，只需要加入如下几个配置项：

{

“serverUrl”: “http://localhost:8080”, – 服务器地址

“allInOne”: true, – 是否将文档合并到一个文件中，一般推荐为true

“outPath”: “src/main/resources/static/doc”, – 指定文档的输出路径

“createDebugPage”: true, – 开启测试

“allInOneDocFileName”:“index.html”, – 自定义文档名称

“projectName”: “初识smart-doc” – 项目名称

}

通过"createDebugPage": true 开启debug功能，在让生成smart-doc生成文档时直接放入到 static/doc/下，这样可以直接启动程序访问页面 http://localhost:8080/doc/index.html进行开发调试。

有的开发人员直接在idea中使用【Open In Browser】打开smart-doc生成的debug页面，如果非要这做，前端js请求后台接口时就出现了跨域。因此你需要在后端配置跨域。

这里以 SpringBoot2.3.x 为例配置后端跨域：

@Configuration

public class WebMvcAutoConfig implements WebMvcConfigurer {

@Bean

public CorsFilter corsFilter() {

final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();

final CorsConfiguration corsConfiguration = new CorsConfiguration();

/* 是否允许请求带有验证信息 */

corsConfiguration.setAllowCredentials(true);

/* 允许访问的客户端域名 */

corsConfiguration.addAllowedOrigin(“*”);

/* 允许服务端访问的客户端请求头 */

corsConfiguration.addAllowedHeader(“*”);

/* 允许访问的方法名,GET POST等 */

corsConfiguration.addAllowedMethod(“*”);

urlBasedCorsConfigurationSource.registerCorsConfiguration(“/**”, corsConfiguration);

return new CorsFilter(urlBasedCorsConfigurationSource);

}

}

开启跨域后我们就可以直接在静态接口页面中进行调试了。

2. 通用响应体

在 “SpringBoot 如何统一后端返回格式？老鸟们都是这样玩的！”一文中我们通过实现 ResponseBodyAdvice对所有返回值进行了包装，给前端返回统一的数据结构ResultData，我们需要让其在接口文档中也有此功能，在配置文件追加配置内容：

{

“responseBodyAdvice”:{ – 通用响应体

“className”:“com.jianzh5.blog.base.ResultData”

}

}

3. 自定义Header

在前后端分离项目中我们一般需要在请求接口时设置一个请求头，如token，Authorization等…后端根据请求头判断是否为系统合法用户，目前smart-doc也对其提供了支持。

在smart-doc配置文件 smart-doc.json中继续追加如下配置内容：

“requestHeaders”: [ //设置请求头，没有需求可以不设置

{

“name”: “token”,//请求头名称

“type”: “string”,//请求头类型

“desc”: “自定义请求头 - token”,//请求头描述信息

“value”:“123456”,//不设置默认null

“required”: false,//是否必须

“since”: “-”,//什么版本添加的改请求头

“pathPatterns”: “/smart/say”,//只有以/smart/say 开头的url才会有此请求头

“excludePathPatterns”:“/smart/add,/smart/edit” // url=/app/page/将不会有该请求头

}

]

效果如下：

4. 参数分组

演示一下smart-doc对于参数分组的支持

新增操作时，age、level为必填项，sex为非必填。

自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

深知大多数Java工程师，想要提升技能，往往是自己摸索成长或者是报班学习，但对于培训机构动则几千的学费，着实压力不小。自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年Java开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上Java开发知识点，真正体系化！

由于文件比较大，这里只是将部分目录截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新！

如果你觉得这些内容对你有帮助，可以扫码获取！！（备注Java获取）

本次面试答案，以及收集到的大厂必问面试题分享：

《互联网大厂面试真题解析、进阶开发核心学习笔记、全套讲解视频、实战项目源码讲义》点击传送门即可获取！
有帮助，可以扫码获取！！（备注Java获取）**

本次面试答案，以及收集到的大厂必问面试题分享：

[外链图片转存中…(img-PeyG9DaV-1713401729467)]

《互联网大厂面试真题解析、进阶开发核心学习笔记、全套讲解视频、实战项目源码讲义》点击传送门即可获取！