Swagger 增强配置：Starter 与属性绑定

配置前提：本文 spring.swagger 等属性来自项目自定义或第三方 Starter，必须先确定依赖坐标与绑定类；它们不是 Spring Boot 的通用属性。

这是一份关于 Swagger 增强版配置（demo-swagger-beauty） 的核心总结笔记。这个 Demo 展示了如何通过自定义配置，让 Swagger 文档更美观、更安全、更规范。

1. 核心目标

通过 application.yml 集中管理 Swagger 行为，实现：

• 文档定制化：定义标题、版本、作者。
• 性能优化：指定扫描包，避免全量扫描。
• 安全加固：开启文档访问登录验证。
• 标准化响应：统一定义全局错误码说明。

2. 配置项深度解析

A. 基础信息 (spring.swagger)

B. 路径控制 (高级)

• base-path: 默认 /**。可改为 /api/**，只文档化特定前缀的接口。
• exclude-path: 黑名单。排除 /actuator/**, /error 等敏感或无用接口。

C. 安全认证 (security) —— 亮点

这是标准 Swagger 不具备的，通常由美化插件（如 Knife4j / swagger-bootstrap-ui）提供。

• filter-plugin: true: 开启文档页面的登录拦截。
• username / password: 设置访问文档的账号密码。
• 价值：防止接口文档被未授权人员随意浏览，泄露系统结构。

D. 全局响应消息 (global-response-messages)

统一定义 HTTP 状态码的含义，无需在每个接口上重复写注解。

• 格式：HTTP方法[索引]: code & message
• 示例：

GET[0]:
  code: 400
  message: Bad Request，一般为请求参数不对

• 效果：在 Swagger UI 的每个接口下方，自动展示统一的“Response Messages”表格，提升文档可读性。

3. 工作原理回顾

1. 启动时：Spring Boot 读取 yml 配置，初始化 Swagger Bean。
2. 扫描时：根据 base-package，利用反射扫描 Controller 和注解。
3. 生成时：组装成符合 OpenAPI 规范的 JSON 数据。
4. 展示时：前端 UI 请求 JSON，渲染出带登录框、统一错误码说明的漂亮页面。

4. 关键避坑指南

1. 非官方配置：
   • spring.swagger 不是 Spring Boot 原生属性。
   • 前提：项目中必须引入了对应的 Starter（如 swagger-spring-boot-starter 或自定义了 @ConfigurationProperties 类），否则这些配置无效。
2. 生产安全：
   • 即使加了密码保护，也建议在生产环境直接 enabled: false。
   • 不要将密码硬编码在代码库中，建议通过环境变量注入。
3. 技术选型：
   • 此 Demo 基于较老的 springfox + swagger-bootstrap-ui。
   • 新项目推荐：使用 SpringDoc OpenAPI + Knife4j。配置更简单，对 Spring Boot 2.6+/3.x 支持更好，且原生支持上述大部分功能。

5. 一句话总结

这个配置文件是 “ Swagger 的最佳实践模板”：它通过限制扫描范围提升了性能，通过登录验证保障了安全，通过全局响应码提升了体验。在团队协作开发中，强烈建议采用此类规范化配置。