使用buf generate生成流式RPC的Swagger时出现未知引用问题

核心问题原因 #

流式RPC生成的Swagger会自动关联错误类型google.rpc.Status，但你的生成配置未将该类型的定义包含到最终的swagger.json中，导致引用无法被识别。

具体解决步骤 #

• 调整buf.gen.yaml的swagger插件配置
  确保使用的swagger生成插件（如protoc-gen-swagger或buf官方swagger插件）开启了包含依赖类型的参数。在buf.gen.yaml中添加如下配置：

  version: v1
  plugins:
    - name: swagger
      out: ./swagger
      opt:
        - include_imports=true
        - include_source_info=true
  

  include_imports=true会让生成器将所有导入的Proto类型定义（包括google/rpc/status.proto中的Status）都加入到swagger.json的definitions区块中。

• 确认buf依赖配置有效性
  检查buf.yaml中的googleapis依赖是否正确，且已完成依赖拉取：

  version: v1
  dependencies:
    - buf.build/googleapis/googleapis
  

  执行buf mod update确保依赖更新完成，保证生成时能正确读取google/rpc/status.proto的内容。

• 手动补全定义（临时应急方案）
  若配置调整后仍未解决问题，可手动在swagger.json的definitions区块中添加google.rpc.Status的定义：

  "google.rpc.Status": {
    "type": "object",
    "properties": {
      "code": {
        "type": "integer",
        "format": "int32"
      },
      "message": {
        "type": "string"
      },
      "details": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/google.protobuf.Any"
        }
      }
    }
  }
  

  注意：若google.protobuf.Any的定义也缺失，需一并补充。优先建议通过配置让生成器自动处理，避免手动维护的繁琐。

验证生成结果 #

重新执行buf generate后，打开swagger.json检查是否存在#/definitions/google.rpc.Status的定义，再验证Swagger的引用错误是否消失。

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