Unused method request/response message rendered in OpenAPI document

[boseabhishek]

🐛 Bug Report

I'm trying to generate Swagger based OpenAPI docs for my grpc services, proxied to REST endpoints via grpc-gateway. Please see details below:

1. I have an accounts.proto whoch has two RPC services - Add and Show. I want to ONLY expose Show( GET /v1/account) which is achieved by using annotation google.api.http and not using teh same on Add.

accounts.proto

syntax = "proto3";

package account;

import "google/api/annotations.proto";
import "protoc-gen-openapiv2/options/annotations.proto";

option go_package = "accounts/pkg/account;account";

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "Account Service";
    version: "1.0";
    contact: {
      name: "some-name";
      url: "https://github.com/some-name";
      email: "some-name@example.com";
    };
  };
  schemes: [HTTP, HTTPS];
  consumes: ["application/json"];
  produces: ["application/json"];
  responses: {
    key: "default";
    value: {
      description: "An unexpected error occurred.";
    }
  }
};


service AccountService {
  rpc Add(AddRequest) returns (AddResponse);
  rpc Show(ShowRequest) returns (ShowResponse) {
    option (google.api.http) = {
      get: "/v1/account"
    };
  }
}

message Money {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
      json_schema: {
          title: "Money"
          description: "Money data structure"
      };
  };

  int64 amount = 1;
}


message AddRequest {
  Money money = 1;
}

message AddResponse {
}

message ShowRequest {
}

message ShowResponse {
  Money money = 1;
} 

2. But on the generated swagger.json, I can see unexpected messages in definitions

swagger.json (excerpt)

"definitions": {
    "accountAddResponse": {
      "type": "object"
    },
    "accountMoney": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "string",
          "format": "int64"
        }
      },
      "description": "Money data structure",
      "title": "Money"
    },
    "accountShowResponse": {
      "type": "object",
      "properties": {
        "money": {
          "$ref": "#/definitions/accountMoney"
        }
      }
    },
    "protobufAny": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "rpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    }
  }

To Reproduce

I use buf generate to generate above file. See buf related files as below:

buf.gen.yaml

version: v1
plugins:
  - plugin: go
    out: gen/go/accounts
    opt:
      - paths=source_relative
  - plugin: go-grpc
    out: gen/go/accounts
    opt:
      - paths=source_relative
  - plugin: grpc-gateway
    out: gen/go/accounts
    opt:
      - paths=source_relative
  - plugin: openapiv2
    out: gen/go/accounts
    opt:
      - ignore_comments=true

buf.yaml

version: v1
deps:
  - buf.build/googleapis/googleapis
  - buf.build/grpc-ecosystem/grpc-gateway 
 

Expected behavior

I get accountAddResponse(shouldn't be as Add is not exposed), protobufAny and rpcStatus as extra and no accountShowRequest

Actual Behavior

I would have expected ONLY accountShowRequest and accountShowResponse.

Your Environment

$ go version
go version go1.24.4 darwin/arm64

Is this a bug or am I missing some settings?

[johanbrandhorst]

Hi, thanks for your bug report! I agree that I am surprised to see accountAddResponse in your rendered definition, but I don't necessarily think that accountShowRequest needs to show up since there are no actual fields in it. Do you think you could share an example repository that reproduces this scenario? I can't see what's wrong from just this snippet unfortunately.

[boseabhishek]

Thanks for your message @johanbrandhorst - I have created a minimal version now.
https://github.com/boseabhishek/foo-accounts. The README is quite basic but has everything you need.

[johanbrandhorst]

Hi, thanks for the repo. I can't explain why accountAddResponse is showing up, but I did find a workaround. If you make use of our visibility rules feature, you can hide the accountAdd method and its request and response message. See this diff:

diff --git a/buf.gen.yaml b/buf.gen.yaml
index 7f2f49a..53e297a 100644
--- a/buf.gen.yaml
+++ b/buf.gen.yaml
@@ -17,3 +17,4 @@ plugins:
     opt:
       - ignore_comments=true
       - disable_default_responses=true
+      - visibility_restriction_selectors=PUBLIC
diff --git a/gen/go/accounts/proto/account/account.swagger.json b/gen/go/accounts/proto/account/account.swagger.json
index 17ff308..758da50 100644
--- a/gen/go/accounts/proto/account/account.swagger.json
+++ b/gen/go/accounts/proto/account/account.swagger.json
@@ -49,9 +43,6 @@
     }
   },
   "definitions": {
-    "accountAddResponse": {
-      "type": "object"
-    },
     "accountMoney": {
       "type": "object",
       "properties": {
diff --git a/proto/account/account.proto b/proto/account/account.proto
index 52953f4..accb22d 100644
--- a/proto/account/account.proto
+++ b/proto/account/account.proto
@@ -3,6 +3,7 @@ syntax = "proto3";
 package account;
 
 import "google/api/annotations.proto";
+import "google/api/visibility.proto";
 import "protoc-gen-openapiv2/options/annotations.proto";
 
 option go_package = "accounts/pkg/account;account";
@@ -30,7 +31,9 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
 
 
 service AccountService {
-  rpc Add(AddRequest) returns (AddResponse);
+  rpc Add(AddRequest) returns (AddResponse) {
+    option (google.api.method_visibility).restriction = "INTERNAL";
+  }
   rpc Show(ShowRequest) returns (ShowResponse) {
     option (google.api.http) = {
       get: "/v1/account"

The reason you're seeing protobufAny and rpcStatus is because they are the default error response message type. If you don't want them, I think you can try setting disable_default_errors=true.

I still think there's probably a bug here - accountAddResponse is showing up in the definitions when there is no method requiring it. With your reproducer it should be possible for someone to pick this up and work on it. Hopefully the workaround will work for you in the meantime.

[boseabhishek]

Many thanks @johanbrandhorst - the workaround does a great job. I have pushed a commit for ref on that repo.