目录
一、选型说明（生产必看）
1. 主流版本区别
二、方案一：Springdoc-OpenAPI（Spring Boot 2.x/3.x 通用，生产主推）
1. 依赖引入（Maven）
Spring Boot 2.x
Spring Boot 3.x（必须用新版）
2. 全局配置类（生产标准配置）
3. 多接口分组（微服务 / 多模块必备）
4. 常用注解（OpenAPI3 注解，替换旧 Swagger）
5. 访问地址
三、方案二：Knife4j（界面增强，传统项目过渡）
1. 依赖（OpenAPI3 版本）
2. 生产核心配置（application.yml）
3. 访问地址
四、生产环境核心管控（重中之重，上线必须配置）
1. 环境隔离：生产环境彻底关闭 Swagger/OpenAPI
方式 1：使用 @Profile（推荐，代码层面控制）
方式 2：配置文件开关（运维可动态控制）
方式 3：Nginx / 网关拦截（网关层兜底）
2. 安全加固（防止接口文档泄露、爬虫、越权）
3. 性能优化（高并发生产环境）
4. 微服务网关适配（Spring Cloud Gateway）
五、生产常见坑 & 解决方案
1. 坑 1：Spring Boot 2.6+ 循环依赖（老 SpringFox）
2. 坑 2：生产忘记关闭文档，接口对外泄露
3. 坑 3：文档参数和实际接口不一致
4. 坑 4：线上 CPU / 内存升高
5. 坑 5：HTTPS 环境下文档请求异常
六、生产环境上线规范（团队标准）
七、生产替代方案（进阶）
本文基于Spring Boot/Spring Cloud主流技术栈，覆盖 Swagger 选型、集成、生产环境安全、权限、性能、灰度、下线、替代方案，全部为生产落地标准方案。
一、选型说明（生产必看）
1. 主流版本区别
- SpringFox（传统 Swagger）
- 依赖：
springfox-swagger2 + springfox-swagger-ui - 问题：停止维护、Spring Boot 2.6+ 循环依赖报错、Spring Boot 3.x 完全不兼容、漏洞多，新项目禁止使用。
- 依赖：
- Knife4j（国内增强版，基于 SpringFox/OpenAPI3）
- 界面友好、离线文档、全局参数、文档加密、导出 MD/HTML，中小企业生产首选。
- Springdoc-OpenAPI（OpenAPI 3 官方实现，推荐）
- 兼容 Spring Boot 2.x/ 3.x、Spring Cloud 全版本、原生 OpenAPI3 规范、无兼容坑，大厂微服务标准方案。
生产环境推荐优先级：Springdoc-OpenAPI（首选） > Knife4j OpenAPI3 > 传统 SpringFox（淘汰）
二、方案一：Springdoc-OpenAPI（Spring Boot 2.x/3.x 通用，生产主推）
1. 依赖引入（Maven）
Spring Boot 2.x
<!-- OpenAPI3 核心 --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.7.0</version> </dependency> <!-- 增强注解、分组、枚举解析（可选） --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-common</artifactId> <version>1.7.0</version> </dependency>Spring Boot 3.x（必须用新版）
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.5.0</version> </dependency>2. 全局配置类（生产标准配置）
实现：文档信息、接口分组、全局请求头 (Token)、忽略静态资源、生产开关
import io.swagger.v3.oas.models.Components; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; import io.swagger.v3.oas.models.info.License; import io.swagger.v3.oas.models.security.SecurityRequirement; import io.swagger.v3.oas.models.security.SecurityScheme; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Profile; /** * OpenAPI3 文档配置 * Profile: dev/test 环境生效，prod 环境自动关闭 */ @Configuration // 仅开发、测试环境开启，生产环境禁用文档入口 @Profile({"dev", "test"}) public class OpenApiConfig { @Value("${spring.application.name}") private String appName; @Bean public OpenAPI customOpenAPI() { // 定义全局 Token 认证（前后端分离项目必备） String authName = "Authorization"; return new OpenAPI() // 全局添加认证请求头 .addSecurityItem(new SecurityRequirement().addList(authName)) .components(new Components() .addSecuritySchemes(authName, new SecurityScheme() .name(authName) .type(SecurityScheme.Type.HTTP) .scheme("bearer") .bearerFormat("JWT"))) // 文档基础信息 .info(new Info() .title(appName + " 接口文档") .version("1.0.0") .description("生产环境接口文档，仅限内部人员查阅") .contact(new Contact() .name("开发团队") .email("dev@xxx.com")) .license(new License().name("Apache 2.0"))); } }3. 多接口分组（微服务 / 多模块必备）
按模块 / 角色拆分文档，避免接口杂乱：
import org.springdoc.core.models.GroupedOpenApi; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Profile; @Configuration @Profile({"dev", "test"}) public class ApiGroupConfig { // 分组1：用户模块 @Bean public GroupedOpenApi userApi() { return GroupedOpenApi.builder() .group("用
