Swagger（OpenAPI）集成标准规范
一、总体原则（先定规矩）
1. 是否集成
swagger集成，但受控启用
| 环境 | Swagger UI | OpenAPI Docs |
|---|---|---|
| dev | ✅ 开启 | ✅ 开启 |
| test | ✅ 开启 | ✅ 开启 |
| prod | ❌ 关闭 | ❌ 关闭 |
2. 设计目标
- 服务于开发 / 联调 / 测试
- 不作为生产运维工具
- 不破坏Security / Auth 体系
- 不污染业务代码
3. 核心设计思想
Swagger 是接口契约说明书，不是权限系统，也不是业务逻辑的一部分。
二、技术选型（统一）
✅ 唯一允许的 Swagger 技术栈
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.8.13</version></dependency>❌ 禁止使用：
- springfox-swagger2
- swagger-bootstrap-ui（已不维护）
- knife4j（如需，后期可封装）
三、模块放置规范（非常重要）
1️⃣ 所属模块
Swagger 相关配置统一放在 common 层
common └── common-swagger ├── config │ └── SwaggerAutoConfiguration.java └── CommonSwaggerModule.java ← 模块入口原因：
- Swagger 是基础设施
- 不属于任何业务模块
- 便于整体启停
四、启用控制策略（核心）
application-dev.yml
springdoc:api-docs:enabled:trueswagger-ui:enabled:truepath:/swagger-ui.htmlapplication-test.yml
springdoc:api-docs:enabled:
