Response codes and descriptions in Swagger docs

[arun0009]

It would be nice if we can specify rest response codes/descriptions via some grpc gateway annotations or some other means.

[achew22]

@arun0009, can you be a little bit more specific about what output changes you would like to see in the swagger docs? Maybe you could put together a PR that has a first pass on some of the ideas?

[arun0009]

Right now, all the responses show up as 200, but it would be nice to have other response messages like 404, 500, 201 & other http response codes with user specified descriptions. I will try and submit a PR over the weekend.

[tmc]

This likely implies options outside of google.api.http annotations.

[tmc]

@arun0009 you might look/comment on #305

[morriswinkler-simple]

Here is a more literate example of the idea:

"paths": {
    "/health-check": {
      "get": {
        "summary": "Returns health status",
        "operationId": "HealthCheck",
        "responses": {
          "200": {
            "description": "", ⬅︎ // no description possible here
            "schema": {
              "$ref": "#/definitions/protobufEmpty"
            }
          }
        },
        "tags": [
          "GardenOpenService"
        ]
      }
    },

would be nice if within the proto file we could add

   // Returns health status
    rpc HealthCheck (google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
       // Really healthy to get some description  ⬅︎
       get: "/health-check"
    };
    }

which could translate to

"paths": {
    "/health-check": {
      "get": {
        "summary": "Returns health status",
        "operationId": "HealthCheck",
        "responses": {
          "200": {
            "description": "Really healthy to get some description  ⬅︎",
            "schema": {
              "$ref": "#/definitions/protobufEmpty"
            }
          }
        },
        "tags": [
          "GardenOpenService"
        ]
      }
    },

What do you think, is this information passed along the proto services slice?

[tmc]

@arun0009 / @morriswinkler-simplesurance -- that suggestion may work for the 200 path but custom proto would be required pretty rapidly IMO

[tmc]

This effort should continue in #145

[johanbrandhorst]

#145 added a lot of the stuff for OpenAPI, but unfortunately it did not add support for custom response codes, so I'm going to bump this. Implementing it at this point should be significantly easier though because of the work done in #145.

[johanbrandhorst]

See https://github.com/grpc-ecosystem/grpc-gateway/pull/145/files#diff-aae53fe2a10de658028c4b8332afb356R62

[achew22]

Agreed, @johanbrandhorst. How can I help you get that PR in?

[johanbrandhorst]

I've opened #663 to help with this.