[已解决] 苍穹外卖：一文搞懂 Swagger/Knife4j 配置，前后端联调效率直接翻倍！

😫 深夜痛点：你还在用微信发 JSON 结构吗？

凌晨 1 点，你刚写完“员工添加”接口，正准备关灯睡觉。
滴滴！前端群里弹出消息：“哥，添加员工的字段是 username 还是 userName？返回值的 status 是 Integer 还是 String？发个文档看看呗？”

小王欲哭无泪：手动写 Word 文档太慢，发 Postman 导出的 JSON 对方又嫌乱。 难道每次改个字段，都要手动更新一遍所有沟通渠道吗？

这就是为什么我们需要 Knife4j。它不仅是 Swagger 的“整容版”，更是后端开发的救命稻草。

🛠️ 核心思路：让代码自己“说话”

Knife4j 的核心思想是逻辑与文档一体化。通过扫描特定的包路径和注解，它能自动提取接口的路径、参数、响应结构，并生成一个精美的 UI 界面。

核心技术栈

Swagger：底层核心，负责解析注解。

Knife4j：增强皮肤，提供更友好的界面和搜索、过滤功能。

WebMvcConfiguration：配置类，用于注册 Bean 和静态资源映射。

🚀 快速解决方案：三步搞定联调神器

1. 引入依赖

在 sky-common 或 pom.xml 中引入 Knife4j 的起步依赖。

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>${knife4j.version}</version></dependency>

2. 编写配置类（核心）

在 WebMvcConfiguration 中定义 Docket 对象。注意这里我们通常会进行分组配置。

@Configuration@Slf4jpublicclassWebMvcConfigurationextendsWebMvcConfigurationSupport{/** * 通过knife4j生成接口文档 * @return */@BeanpublicDocketdocket(){log.info("准备生成接口文档...");ApiInfoapiInfo=newApiInfoBuilder().title("苍穹外卖项目接口文档").version("2.0").description("苍穹外卖项目接口文档").build();Docketdocket=newDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select()// 指定生成接口需要扫描的包.apis(RequestHandlerSelectors.basePackage("com.sky.controller")).paths(PathSelectors.any()).build();returndocket;}}

3. 设置静态资源映射（避坑关键点！）

注意：很多同学配置完发现 404，就是因为拦截器或静态资源路径没放行。由于 Knife4j 的资源不在标准路径下，必须手动配置。

/** * 设置静态资源映射 * @param registry */protectedvoidaddResourceHandlers(ResourceHandlerRegistryregistry){log.info("开始设置静态资源映射...");registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}

📊 逻辑流程图

接口文档是如何从你的代码变成页面的？看这张图就懂了：

📉 对比信息：原生 Swagger vs Knife4j

💡 底层逻辑分析 & 面试加分项

Q：为什么生产环境要关闭 Swagger/Knife4j？

面试加分回答：安全隐患！接口文档暴露了系统的所有入口，容易被恶意爬取数据或进行暴力破解。

避坑小贴士：建议在配置类上增加@Profile({“dev”, “test”}) 注解，确保文档只在开发和测试环境可见。

Q：Knife4j 2.x 和 3.x 有什么主要区别？

底层解析：2.x 主要基于Springfox (Swagger 2)，而 3.x 开始兼容Springdoc (OpenAPI 3)。

配置方式：3.x 更加强调yml 配置化，减少了 Java 代码的编写。

🔚 总结与互动

配置好 Knife4j 后，你只需要把 http://localhost:8080/doc.html 扔给前端，剩下的时间就可以优雅地喝咖啡了。

👨‍💻 每日一思：

如果在多模块（微服务）架构下，如何实现一个统一的网关文档入口，聚合所有微服务的接口？

最后，如果你觉得这篇文章让你联调少抓了三根头发，别忘了：
✅点赞（你的鼓励是我持续输出的动力）
⭐收藏（方便下次联调报错时随时翻阅）
👤关注（带你解锁更多《苍穹外卖》实战姿势）

评论区互动：你觉得联调中最让你崩溃的事情是什么？