Add example of using ref to reference unused messages for openapi.json inclusion

[protiumx]

🚀 Feature

When defining generic responses for different status codes, I use an unbound message as follows

message GenericResponse {
  repeated string resources = 1;
  repeated string errors = 2;
}

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  responses: {
    key: "400"
    value: {
      description: "Returned when the request is malformed."
      schema: {
        json_schema: {ref: "#/definitions/GenericResponse"}
      }
    }
  }
}

Because the message GenericResponse is not bound to any rpc, the swagger definition is not generated.
The workaround is to generate a No-op service and rpc that use the message

service ExampleService {
  rpc Create(google.protobuf.Empty) returns (GenericResponse);
}

Request

Allow for the generation of unbounded messages via configuration. Similar to the generate_unbound_methods flag.

[johanbrandhorst]

Hi, thanks for the issue. I don't think this should need a new flag, I would expect us to be able to detect these top level definitions and use that to include the message. Does it work if you tie this response to a specific RPC instead? I think we had to do something similar for the gRPC Status message type.

[protiumx]

Hi @johanbrandhorst
Correct, at the moment I can get the message schema generated by binding it to a no-op RPC, which I ought to replace with this feature request. In the Schema field for the top level options, I don't see a way I could bind/include the message, I only see json_schema: {ref: "#/definitions/GenericResponse"}

[johanbrandhorst]

So as it happens we have an example of this working when defined globally as in your example:

• Definition here:

  grpc-gateway/examples/internal/proto/examplepb/a_bit_of_everything.proto

  Lines 151 to 169 in 250bec2

  	responses: {
  	key: "500"
  	value: {
  	description: "Server error"
  	headers: {
  	key: "X-Correlation-Id"
  	value: {
  	description: "Unique event identifier for server requests"
  	type: "string"
  	format: "uuid"
  	default: "\"2438ac3c-37eb-4902-adef-ed16b4431030\""
  	pattern: "^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$"
  	}
  	}
  	schema: {
  	json_schema: {ref: ".grpc.gateway.examples.internal.proto.examplepb.ErrorResponse"}
  	}
  	}
  	}

• Rendered here (and in lots of other places):

  grpc-gateway/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json

  Lines 82 to 87 in 250bec2

  	"500": {
  	"description": "Server error",
  	"schema": {
  	"$ref": "#/definitions/examplepbErrorResponse"
  	}
  	},

As you can see, ErrorResponse isn't used in any rpcs in this protobuf but it's still being rendered. Could you try to reproduce the problem and compare it to the one in a_bit_of_everything.proto?

[protiumx]

Amazing, using the schema.$ref works for my use case. Thanks @johanbrandhorst .
It could be worth to add a note in the docs as this is only visible in the examples, but I consider this feature request resolved.

[johanbrandhorst]

Great idea, would you be willing to contribute a little section to the docs? The files are in https://github.com/grpc-ecosystem/grpc-gateway/tree/main/docs/docs.