Option to turn off default 200 response generation in protoc-gen-openapiv2

[sbulman]

🚀 Feature

I was wondering if it is feasible to have a similar option to disableDefaultErrors to turn off the default generation of the 200 responses? Has this been considered and dismissed?

Some examples:

• I have a post request where I only want to return 201 Created (or error codes)
• I have a delete request where I only want to return 204 No Content (or error codes)
• I have a head request where I only want to return 204 No Content

This would marry nicely with the ability to inject a httpResponseModifier in the mux

[johanbrandhorst]

Hi, thanks for your issue. I don't know that we've discussed this before, but I'm initially a bit hesitant. Default errors were introduced because we have a purpose-built error handler option. Disabling the 200 responses feels more drastic, especially since the ForwardResponseOption isn't really about changing the response entirely from what the HTTP description is (it's more of a setting headers sort of thing). The 200 response in success cases come from the OK status code translation (https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto#L35) and adding this option means that the protobuf definitions are no longer the source of truth for your API output. I suppose that ship sort of sailed away already if you use swagger though. I'm open to considering it, but as with other feature requests I'd usually like to see the same ask from at least two users. I'd like to leave this issue open and see if it gathers more momentum before committing to this option. How does that sound?

[sbulman]

Thank you for your considered response. Perhaps one option to reduce the impact could be to provide the option and only apply it if there are explicit '2xx' responses added as options to the protobuf definition. My thinking is that if a user has gone to the trouble of defining their own responses and enable an option to disable the default 200 swagger response there is real intent. Happy to wait and see if there is more momentum from others, and perhaps hear if others have worked around this in other ways (it kinda feels uncomfortable to have a response code documented in the swagger if the server will never generate it).

[johanbrandhorst]

I don't think we'd need any extra logic like that TBH if we do add it, it'd be simpler just to disable the default response generator, it shouldn't interact too badly with any other options, obviously it'd mean the user has to carefully make sure they're still defining responses for all their RPCs but I'm okay with that, you could always add a default 200 OK at the top level.

[krak3n]

This is effecting me as well, we are looking to define our contracts in protocol buffers but we need to (at least in the short term) support OpenAPI and some of our endpoints return 201 instead of 200.

Perhaps there could be a way for us to mark a defined response as the default?

For example:

service FooService {
  rpc CreateFoo(CreateFooRequest) returns (CreateFooResponse) {
    option (google.api.http) = {
      post: "/v2/foos"
      body: "*"
    };

    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "Create a new Foo.";
      description: "Creates a Foo. You may create up to 5 Foos.";
      operation_id: "create_foo";
      tags: "foos"
      responses: {
        default: true,
        key: "201",
        value: {
          description: "Created";
          schema: {
            json_schema: {ref: ".Foo"}
          }
        }
      }
    };
  }
}

[johanbrandhorst]

Hi Chris, great to hear from you! I think this certainly means that we have enough of a need for this. As I said, I don't think we need to add any annotations, we can simply turn off the default response generation with a flag. Would you be interested in contributing this?

[krak3n]

Hey @johanbrandhorst yes absolutely would be.

[krak3n]

See #3006 for implementation.