如何在Spring Boot多模块项目中为gRPC跨服务调用添加Swagger UI文档

Swagger/OpenAPI原生聚焦于RESTful接口，但针对Spring Boot项目里的RPC调用（比如Feign、Dubbo这类），可以通过适配方案实现文档化，以下是具体场景的解决方法：

一、基于Feign的RPC调用（Spring Cloud生态） #

如果serviceA通过Feign调用serviceB，整合成本很低：

• 在serviceB端：给对外暴露的接口添加Swagger/OpenAPI注解（如@Operation、@ApiResponse、@Schema），生成标准的OpenAPI文档。建议把serviceB的API接口抽成独立的公共模块，方便serviceA依赖复用。
• 在serviceA端：让Feign客户端接口直接继承公共模块里的API接口，同时配置SpringDoc/SpringFox（选其一即可）。以SpringDoc为例，只需在配置类中开启Feign接口的文档扫描，就能让serviceA的Swagger UI同时展示自身接口和调用serviceB的RPC接口，还可通过@OpenAPIDefinition配置serviceB的服务地址，方便在UI中直接测试调用。

二、基于Dubbo的原生RPC调用 #

对于Dubbo这类非HTTP协议的RPC，需要借助插件或自定义实现：

• 使用Dubbo Swagger插件：比如dubbo-swagger插件，它能自动扫描Dubbo接口和方法上的Swagger注解，生成符合OpenAPI规范的文档。只需在Dubbo接口上添加@Api、@ApiOperation等注解，配置插件暴露文档端点后，就能通过Swagger UI查看RPC接口详情。
• 自定义文档生成：如果没有合适的插件，可自行编写代码扫描Dubbo接口的元数据（方法签名、参数、返回值），结合注解生成OpenAPI格式的JSON文件，再将该文件配置给Swagger UI加载展示。

关键注意事项 #

• 无论哪种方案，都要给RPC接口的参数、返回值、异常场景添加明确的Swagger注解，确保文档能清晰展示字段含义、数据类型和约束。
• 跨服务调用时，可在Swagger UI中配置多环境的serviceB地址（通过servers配置），方便不同环境下的接口测试。

内容的提问来源于stack exchange，提问作者Roohi