商用项目Swagger（OpenAPI）集成标准规范

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.html

application-test.yml

springdoc:api-docs:enabled: