微服务拆分后，接口文档如果分散在三个端口，前端要来回切换。开发环境的 Gateway 使用 SpringDoc 聚合 Swagger UI，一个页面切换 Provider、Consumer 和 Mail。
一、聚合入口
http://localhost/swagger-ui.html
页面里的文档组类似：
Provider v1
Consumer v1
Mail v1
二、OpenAPI JSON 走网关
Provider 的文档地址形如：
/api/v1/provider/v3/api-docs/v1-provider
网关根据模块名转发到对应服务，再把标准前缀重写为 SpringDoc 原生路径。
三、只在开发环境开放
生产 Profile 会关闭：
springdoc.api-docs.enabled
springdoc.swagger-ui.enabled
同时网关不注册 OpenAPI 转发路由。文档能暴露接口结构和参数模型，默认不应该出现在生产入口。
四、验证不能只看状态码
WebMVC 全局异常处理可能把不存在路径包装成 HTTP 200，响应体是 code=102。生产验证文档关闭时，要检查响应体，而不是只看 404。
五、经验总结
聚合文档提升的是协作效率，但必须和 Profile 绑定。开发默认开，生产默认关，这是比较稳的默认值。