protoc-gen-swagger doesn't generate any request objects for GET/DELETE

[Sahasrara]

Bug reports:

Fill in the following sections with explanations of what's gone wrong.

Steps you follow to reproduce the error:

1. I wrote a simple gRPC proto file with one GET endpoint.
2. I run protoc with swagger gen
3. The Response object appears in my swagger file, but the request does not.

What did you expect to happen instead:

1. I assumed the swagger documentation would be complete.

I noticed #505 which seemed similar. I tried commenting removing the if statement below this comment:
(Line: 171) // Request may be fully included in query

and that seemed to help. I have no idea if that has any side effects, I never really dug into the code. This gets me unblocked, but I did want to file a report in case anyone else is having this issue.

What's your theory on why it isn't working:
I really couldn't say. I didn't read all the code.

[johanbrandhorst]

Thanks for your issue report. Could you include an example protofile that reproduces the issue?

[Sahasrara]

Sure thing:

syntax = "proto3";

package test;

import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
import "google/api/annotations.proto";
import "protoc-gen-swagger/options/annotations.proto";

option go_package = "gitlab.myteksi.net/gophers/go/ads/admanager/pb";
option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
  base_path: "/test";
  info: {
    title: "Test";
    version: "1.0";
  };
};

service Admanager {
  rpc GetCooldude(GetCooldudeRequest) returns (GetCooldudeResponse) {
    option (google.api.http) = {
      get: "/Cooldudes/{CooldudeID}"
    };
  }
}

message Cooldude {
  uint32 CooldudeID = 1;
  string Name = 2;
  bool Deleted = 3;
  bool Active = 4;
  uint32 ExternalCooldudeID = 16;
}
message GetCooldudeRequest {
  uint32 CooldudeID = 1;
}
message GetCooldudeResponse {
  Cooldude Cooldude = 1;
}

[johanbrandhorst]

Is it possible the request object isn't in the file as you expected because its a path parameter? What does the generated swagger file look like? What did you expect it to look like?

[Sahasrara]

I'm not sure I understand. The request object contains a path parameter, but it's not "a path parameter." As for the generated swagger file, I see everything I expect except no GetCooldudeRequest.

This is missing:

  GetCooldudeRequest:
    description: GetCooldudeRequest is the request object for GetCooldude.
    properties:
      CooldudeID:
        format: int64
        type: integer
    type: object

[johanbrandhorst]

It doesn't create a type definition unless it needs to. This get request has only one parameter, and it's populated in the path (i.e. by calling yourapiserver.com/Cooldudes/1337). If you look for the generated definition of the method, rather than the request, you'll find that it has defined all parameters required by the request. I think this is a simple misunderstanding and not a bug, so I will close it. Feel free to reply again if there's anything unclear.

[Sahasrara]

I don't think I understand? The response objects are all generated correctly. The requests are all missing. You're saying that's not a bug? This happens when there are query parameters, it happens when there are path parameters. Anything without a body will not have it's request object show up in swagger.

[johanbrandhorst]

Yes, that is indeed intentional. Why would they?

[johanbrandhorst]

It's when there is no need to provide any JSON input that it doesn't get generated.

[Sahasrara]

Doesn't that leave query parameters undocumented? In my case, the swagger is being used to generate a client for the API and unless these requests are documented, it has no idea how to construct requests.

[johanbrandhorst]

No, the path and query parameters are defined in the method definition, as per the OpenAPI v2 standard. Your swagger generator should have no problems generating appropriate request objects.

[Sahasrara]

OK i'm going to circle back with the folks who wrote the generator. Thanks for your help!

[johanbrandhorst]

Which generator is this, out of curiosity? I've used different generators with the generated swagger files without problems. Make sure it's a v2 generator though.

[myt588]

For anyone who is missing all the Request type in the generated json file, you can add body: "*" in the option to generate the Request type

ex:

service Admanager {
  rpc GetCooldude(GetCooldudeRequest) returns (GetCooldudeResponse) {
    option (google.api.http) = {
      post: "/Cooldudes/{CooldudeID}"
      body: "*"
    };
  }
}