目录一、选型说明（生产必看）1. 主流版本区别二、方案一：Springdoc-OpenAPI（Spring Boot 2.x/3.x 通用，生产主推）1. 依赖引入（Maven）Spring Boot 2.xSpring 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 groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-ui/artifactId version1.7.0/version /dependency !-- 增强注解、分组、枚举解析（可选） -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-common/artifactId version1.7.0/version /dependencySpring Boot 3.x（必须用新版）dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.5.0/version /dependency2. 全局配置类（生产标准配置）实现：文档信息、接口分组、全局请求头 (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("用
Java 生产环境 Swagger 实战
目录一、选型说明（生产必看）1. 主流版本区别二、方案一：Springdoc-OpenAPI（Spring Boot 2.x/3.x 通用，生产主推）1. 依赖引入（Maven）Spring Boot 2.xSpring 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 groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-ui/artifactId version1.7.0/version /dependency !-- 增强注解、分组、枚举解析（可选） -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-common/artifactId version1.7.0/version /dependencySpring Boot 3.x（必须用新版）dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.5.0/version /dependency2. 全局配置类（生产标准配置）实现：文档信息、接口分组、全局请求头 (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("用
