1. 为什么需要网关层统一管理Swagger文档在微服务架构中API文档管理一直是个让人头疼的问题。我经历过一个项目有十几个微服务每个服务都自带Swagger UI前端同事每次调试接口要在不同端口间来回切换光记文档地址就够写个小本本了。更麻烦的是当服务需要认证时每个Swagger页面都要单独配置Token效率低得让人想摔键盘。Spring Cloud Gateway作为统一入口的优势这时候就体现出来了。通过网关聚合所有下游服务的API文档前端只需要记住一个地址所有接口文档尽收眼底。实测下来这种方案能让联调效率提升至少50%再也不用在多个浏览器标签页之间反复横跳了。但这里有个技术难点Spring Cloud Gateway基于WebFlux响应式编程而常规服务多用Spring MVC。这两种技术栈的Swagger集成方式完全不同就像安卓和iOS的充电接口不兼容一样让人抓狂。接下来我会详细拆解如何用springdoc-openapi这个神器解决这个兼容性问题。2. 项目环境与依赖配置2.1 基础环境准备先晒下我的实战环境配置这些版本经过严格测试可以避免大部分兼容性问题JDK 17必须≥17低版本会有模块化问题Spring Boot 3.3.5注意3.x系列才支持Jakarta EESpring Cloud 2023.0.3Spring Cloud Alibaba 2023.0.1.2关键依赖版本号要锁死我吃过版本冲突的亏properties springdoc.version2.6.0/springdoc.version swagger-annotations-jakarta.version2.2.28/swagger-annotations-jakarta.version /properties2.2 依赖选择避坑指南这里有个大坑我踩过三次WebFlux和WebMVC的Swagger starter不能混用网关和其他服务要区别配置!-- 网关专用WebFlux响应式 -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webflux-ui/artifactId /dependency !-- 普通服务专用WebMVC -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId /dependency曾经有同事在网关误用webmvc-ui启动直接报ClassNotFoundException排查了半天才发现是starter选错了。这两个starter的区别就像汽油车和电动车看着都是车但动力系统完全不同。3. 通用Swagger模块设计3.1 自动化配置封装为了避免每个服务重复配置我抽象了一个common-swagger模块。核心是这个自动配置类AutoConfiguration EnableConfigurationProperties(SpringDocProperties.class) public class SpringDocAutoConfiguration { Bean public OpenAPI openApi(SpringDocProperties properties) { return new OpenAPI() .info(new Info().title(properties.getTitle())) .addSecurityItem(new SecurityRequirement().addList(JWT)) .components(new Components() .addSecuritySchemes(JWT, new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme(bearer))); } }配套的配置属性类支持yml动态配置springdoc: gatewayUrl: http://localhost:8080 info: title: 智能分析平台API version: 1.0.03.2 统一异常处理技巧所有Swagger相关端点要跳过认证我在网关的JWT过滤器里加了白名单private static final ListString SWAGGER_WHITELIST Arrays.asList( /swagger-ui/**, /v3/api-docs/**, /swagger-resources/** ); if (SWAGGER_WHITELIST.stream().anyMatch(path - pathMatcher.match(path, requestPath))) { return chain.filter(exchange); // 放行Swagger请求 }这个配置要特别注意路径通配符的写法有次我把/**写成/*导致css文件被拦截Swagger页面变成光秃秃的HTML还以为是被黑客攻击了。4. 网关层特殊配置4.1 动态文档聚合网关最核心的功能是自动发现服务并聚合文档。这个监听器会在服务注册时动态更新Swagger分组public class SwaggerDocRegister extends SubscriberInstancesChangeEvent { Override public void onEvent(InstancesChangeEvent event) { SetSwaggerUrl urls discoveryClient.getServices() .stream() .map(service - new SwaggerUrl(service, / service /v3/api-docs)) .collect(Collectors.toSet()); swaggerUiConfigProperties.setUrls(urls); } }4.2 响应式路由配置WebFlux环境下静态资源路由要特殊处理否则Swagger UI的css/js会加载失败spring: cloud: gateway: routes: - id: swagger-ui uri: classpath:/META-INF/resources/webjars/swagger-ui/ predicates: - Path/swagger-ui/** filters: - RewritePath/swagger-ui/(?path.*), /$\{path}这个配置中有个玄学问题路径重写必须用$\{path}而不是${path}否则Spring会误认为是SpEL表达式。这个坑我花了周末两天才爬出来。5. 实战效果与调优5.1 文档访问演示启动所有服务后访问http://网关地址/swagger-ui.html会看到这样的界面[下拉菜单] - 用户服务 (user-service) - 订单服务 (order-service) - 支付服务 (payment-service)点击服务名会自动加载对应文档。这里有个性能优化点默认情况下每次切换服务都会重新请求文档可以通过缓存策略优化Bean public SwaggerUiConfigParameters swaggerUiConfigParameters() { SwaggerUiConfigParameters parameters new SwaggerUiConfigParameters(); parameters.setDocExpansion(none); // 默认折叠所有标签 parameters.setDefaultModelsExpandDepth(-1); // 隐藏模型定义 return parameters; }5.2 安全加固建议虽然文档方便但生产环境要特别注意通过springdoc.show-actuator隐藏actuator端点使用Profile(dev)限制只在开发环境启用配置HTTP Basic认证springdoc: swagger-ui: basic-auth: username: admin password: 123456在我的生产实践中曾经因为没做访问控制导致API文档被爬虫抓取差点造成信息泄露。现在每次部署都会用Postman做个安全扫描。6. 常见问题解决方案问题1文档加载时报Failed to load API definition排查步骤检查网关路由配置是否正确直接访问/v3/api-docs看原始JSON是否正常查看浏览器控制台具体错误问题2Swagger页面样式丢失解决方案Configuration public class SwaggerResourceConfig implements WebFluxConfigurer { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/swagger-ui/**) .addResourceLocations(classpath:/META-INF/resources/webjars/swagger-ui/4.18.1/); } }问题3OAuth2认证集成需要在OpenAPI配置中添加安全方案new OpenAPI() .components(new Components() .addSecuritySchemes(oauth2, new SecurityScheme() .type(SecurityScheme.Type.OAUTH2) .flows(new OAuthFlows() .implicit(new OAuthFlow() .authorizationUrl(https://auth-server/oauth/authorize) .scopes(new Scopes() .addString(read, Read access))))) );这些解决方案都是我在真实项目中踩坑后总结出来的特别是OAuth2集成那块官方文档说得云里雾里最后是通过反编译Swagger UI源码才找到正确配置方式。
Spring Cloud Gateway与WebFlux下Swagger3的集成与配置实战
1. 为什么需要网关层统一管理Swagger文档在微服务架构中API文档管理一直是个让人头疼的问题。我经历过一个项目有十几个微服务每个服务都自带Swagger UI前端同事每次调试接口要在不同端口间来回切换光记文档地址就够写个小本本了。更麻烦的是当服务需要认证时每个Swagger页面都要单独配置Token效率低得让人想摔键盘。Spring Cloud Gateway作为统一入口的优势这时候就体现出来了。通过网关聚合所有下游服务的API文档前端只需要记住一个地址所有接口文档尽收眼底。实测下来这种方案能让联调效率提升至少50%再也不用在多个浏览器标签页之间反复横跳了。但这里有个技术难点Spring Cloud Gateway基于WebFlux响应式编程而常规服务多用Spring MVC。这两种技术栈的Swagger集成方式完全不同就像安卓和iOS的充电接口不兼容一样让人抓狂。接下来我会详细拆解如何用springdoc-openapi这个神器解决这个兼容性问题。2. 项目环境与依赖配置2.1 基础环境准备先晒下我的实战环境配置这些版本经过严格测试可以避免大部分兼容性问题JDK 17必须≥17低版本会有模块化问题Spring Boot 3.3.5注意3.x系列才支持Jakarta EESpring Cloud 2023.0.3Spring Cloud Alibaba 2023.0.1.2关键依赖版本号要锁死我吃过版本冲突的亏properties springdoc.version2.6.0/springdoc.version swagger-annotations-jakarta.version2.2.28/swagger-annotations-jakarta.version /properties2.2 依赖选择避坑指南这里有个大坑我踩过三次WebFlux和WebMVC的Swagger starter不能混用网关和其他服务要区别配置!-- 网关专用WebFlux响应式 -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webflux-ui/artifactId /dependency !-- 普通服务专用WebMVC -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId /dependency曾经有同事在网关误用webmvc-ui启动直接报ClassNotFoundException排查了半天才发现是starter选错了。这两个starter的区别就像汽油车和电动车看着都是车但动力系统完全不同。3. 通用Swagger模块设计3.1 自动化配置封装为了避免每个服务重复配置我抽象了一个common-swagger模块。核心是这个自动配置类AutoConfiguration EnableConfigurationProperties(SpringDocProperties.class) public class SpringDocAutoConfiguration { Bean public OpenAPI openApi(SpringDocProperties properties) { return new OpenAPI() .info(new Info().title(properties.getTitle())) .addSecurityItem(new SecurityRequirement().addList(JWT)) .components(new Components() .addSecuritySchemes(JWT, new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme(bearer))); } }配套的配置属性类支持yml动态配置springdoc: gatewayUrl: http://localhost:8080 info: title: 智能分析平台API version: 1.0.03.2 统一异常处理技巧所有Swagger相关端点要跳过认证我在网关的JWT过滤器里加了白名单private static final ListString SWAGGER_WHITELIST Arrays.asList( /swagger-ui/**, /v3/api-docs/**, /swagger-resources/** ); if (SWAGGER_WHITELIST.stream().anyMatch(path - pathMatcher.match(path, requestPath))) { return chain.filter(exchange); // 放行Swagger请求 }这个配置要特别注意路径通配符的写法有次我把/**写成/*导致css文件被拦截Swagger页面变成光秃秃的HTML还以为是被黑客攻击了。4. 网关层特殊配置4.1 动态文档聚合网关最核心的功能是自动发现服务并聚合文档。这个监听器会在服务注册时动态更新Swagger分组public class SwaggerDocRegister extends SubscriberInstancesChangeEvent { Override public void onEvent(InstancesChangeEvent event) { SetSwaggerUrl urls discoveryClient.getServices() .stream() .map(service - new SwaggerUrl(service, / service /v3/api-docs)) .collect(Collectors.toSet()); swaggerUiConfigProperties.setUrls(urls); } }4.2 响应式路由配置WebFlux环境下静态资源路由要特殊处理否则Swagger UI的css/js会加载失败spring: cloud: gateway: routes: - id: swagger-ui uri: classpath:/META-INF/resources/webjars/swagger-ui/ predicates: - Path/swagger-ui/** filters: - RewritePath/swagger-ui/(?path.*), /$\{path}这个配置中有个玄学问题路径重写必须用$\{path}而不是${path}否则Spring会误认为是SpEL表达式。这个坑我花了周末两天才爬出来。5. 实战效果与调优5.1 文档访问演示启动所有服务后访问http://网关地址/swagger-ui.html会看到这样的界面[下拉菜单] - 用户服务 (user-service) - 订单服务 (order-service) - 支付服务 (payment-service)点击服务名会自动加载对应文档。这里有个性能优化点默认情况下每次切换服务都会重新请求文档可以通过缓存策略优化Bean public SwaggerUiConfigParameters swaggerUiConfigParameters() { SwaggerUiConfigParameters parameters new SwaggerUiConfigParameters(); parameters.setDocExpansion(none); // 默认折叠所有标签 parameters.setDefaultModelsExpandDepth(-1); // 隐藏模型定义 return parameters; }5.2 安全加固建议虽然文档方便但生产环境要特别注意通过springdoc.show-actuator隐藏actuator端点使用Profile(dev)限制只在开发环境启用配置HTTP Basic认证springdoc: swagger-ui: basic-auth: username: admin password: 123456在我的生产实践中曾经因为没做访问控制导致API文档被爬虫抓取差点造成信息泄露。现在每次部署都会用Postman做个安全扫描。6. 常见问题解决方案问题1文档加载时报Failed to load API definition排查步骤检查网关路由配置是否正确直接访问/v3/api-docs看原始JSON是否正常查看浏览器控制台具体错误问题2Swagger页面样式丢失解决方案Configuration public class SwaggerResourceConfig implements WebFluxConfigurer { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/swagger-ui/**) .addResourceLocations(classpath:/META-INF/resources/webjars/swagger-ui/4.18.1/); } }问题3OAuth2认证集成需要在OpenAPI配置中添加安全方案new OpenAPI() .components(new Components() .addSecuritySchemes(oauth2, new SecurityScheme() .type(SecurityScheme.Type.OAUTH2) .flows(new OAuthFlows() .implicit(new OAuthFlow() .authorizationUrl(https://auth-server/oauth/authorize) .scopes(new Scopes() .addString(read, Read access))))) );这些解决方案都是我在真实项目中踩坑后总结出来的特别是OAuth2集成那块官方文档说得云里雾里最后是通过反编译Swagger UI源码才找到正确配置方式。
