fix: protoc-gen-swagger: get wrong second services method comments

[chinaran]

When a service.proto have more then one services, the protoc-gen-swagger tool can not find right other(not the first one) service's method comments.
I changed protoComments's argument, then the service.swagger.json's summary field was right.
But I'm not sure is the right way to fix it.
Please checkout, thanks.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[johanbrandhorst]

Hi! Thanks for the interest in the project! Instead of this, could you raise an issue with an example of how this bug exhibits itself? With a failing example it will be easy to create a test that we can test a fix against. You could try adding one to this PR too.

The generation failure is because you haven't regenerated the files, please see the contribution documentation for a command that will help you do this.

[kazhuravlev]

Hi, I have example of invalid output:

contracts.proto

syntax = "proto3";

package contracts;
option optimize_for = SPEED;

import "google/api/annotations.proto";

message M {}

service Service1 {
    // Service1: Method1
    rpc Method1 (M) returns (M) {
        option (google.api.http) = {
            post: "/Service1/Method1"
            body: "*"
        };
    }
    // Service1: Method2
    rpc Method2 (M) returns (M) {
        option (google.api.http) = {
            post: "/Service1/Method2"
            body: "*"
        };
    }
}

service Service2 {
    // Service2: Method1
    rpc Method1 (M) returns (M) {
        option (google.api.http) = {
            post: "/Service2/Method1"
            body: "*"
        };
    }
    // Service2: Method2
    rpc Method2 (M) returns (M) {
        option (google.api.http) = {
            post: "/Service2/Method2"
            body: "*"
        };
    }
}

contracts.swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "contracts.proto",
    "version": "version not set"
  },
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/Service1/Method1": {
      "post": {
        "summary": "Service1: Method1",
        "operationId": "Method1",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/contractsM"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/contractsM"
            }
          }
        ],
        "tags": [
          "Service1"
        ]
      }
    },
    "/Service1/Method2": {
      "post": {
        "summary": "Service1: Method2",
        "operationId": "Method2",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/contractsM"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/contractsM"
            }
          }
        ],
        "tags": [
          "Service1"
        ]
      }
    },
    "/Service2/Method1": {
      "post": {
        "summary": "Service1: Method1",
        "operationId": "Method1",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/contractsM"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/contractsM"
            }
          }
        ],
        "tags": [
          "Service2"
        ]
      }
    },
    "/Service2/Method2": {
      "post": {
        "summary": "Service1: Method2",
        "operationId": "Method2",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/contractsM"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/contractsM"
            }
          }
        ],
        "tags": [
          "Service2"
        ]
      }
    }
  },
  "definitions": {
    "contractsM": {
      "type": "object"
    }
  }
}

and result screenshot

[johanbrandhorst]

Nice, so it's just the summary that's wrong? Could you try to add either this whole file or something equivalent to one of the existing files and write a test that errors? That'd be well on the way to a contribution to fix this.

[chinaran]

@googlebot I signed it!

[googlebot]

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

[johanbrandhorst]

Could you please regenerate the files so we can see what difference this makes? See https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md#i-want-to-regenerate-the-files-after-making-changes

[chinaran]

@johanbrandhorst Now I found the summary and description is wrong.
https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/proto/examplepb/a_bit_of_everything.proto#L524
You could look this example proto file, and Empty do not have comments.
But the swagger.json file have.
https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/proto/examplepb/a_bit_of_everything.swagger.json#L1929

[johanbrandhorst]

You still need to regenerate the files or CI will not pass.

[chinaran]

@johanbrandhorst ok, I will regenerate the files.

[codecov-io]

Codecov Report

Merging #1116 into master will not change coverage.
The diff coverage is 100%.

@@           Coverage Diff           @@
##           master    #1116   +/-   ##
=======================================
  Coverage   53.88%   53.88%           
=======================================
  Files          42       42           
  Lines        4166     4166           
=======================================
  Hits         2245     2245           
  Misses       1677     1677           
  Partials      244      244

Impacted Files	Coverage Δ
protoc-gen-swagger/genswagger/template.go	57.19% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 29dafe9...4639a8a. Read the comment docs.

[chinaran]

@johanbrandhorst I have already regenerated the files.
Please checkout.

[johanbrandhorst]

Thanks, this all looks correct!

[kazhuravlev]

Please, write the test, that cover this case, @chinaran