fix rpc comment generation against allow_merge

[kentdotn]

References to other Issues or PRs

Fixes #664

Have you read the Contributing Guidelines?

Yes

Brief description of what is fixed or changed

Currently protoc-gen-swagger does not make rpc comments properly when you give allow_merge=yes option.
This PR fixes the problem.

For example, here is a diff between ones generated by current master and this PR:

diff --git a/examples/internal/proto/examplepb/swagger_merge.swagger.json b/examples/internal/proto/examplepb/swagger_merge.swagger.json
index b8d4ca0..39e37d5 100644
--- a/examples/internal/proto/examplepb/swagger_merge.swagger.json
+++ b/examples/internal/proto/examplepb/swagger_merge.swagger.json
@@ -82,6 +82,8 @@
     },
     "/v1/example/b/1": {
       "post": {
+        "summary": "ServiceB.MethodOne receives InMessageB and returns OutMessageB",
+        "description": "Here is the detail explanation about ServiceB.MethodOne.",
         "operationId": "ServiceB_MethodOne",
         "responses": {
           "200": {
@@ -114,6 +116,8 @@
     },
     "/v1/example/b/2": {
       "post": {
+        "summary": "ServiceB.MethodTwo receives OutMessageB and returns InMessageB",
+        "description": "Here is the detail explanation about ServiceB.MethodTwo.",
         "operationId": "ServiceB_MethodTwo",
         "responses": {
           "200": {

[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.

[codecov-commenter]

Codecov Report

Merging #1445 into master will increase coverage by 0.05%.
The diff coverage is 85.71%.

@@            Coverage Diff             @@
##           master    #1445      +/-   ##
==========================================
+ Coverage   54.27%   54.33%   +0.05%     
==========================================
  Files          42       42              
  Lines        4394     4399       +5     
==========================================
+ Hits         2385     2390       +5     
  Misses       1752     1752              
  Partials      257      257              

Impacted Files	Coverage Δ
protoc-gen-swagger/genswagger/generator.go	10.31% <0.00%> (ø)
protoc-gen-swagger/genswagger/template.go	57.90% <100.00%> (+0.17%)	⬆️

---

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 6dd8bd6...e10141e. Read the comment docs.

[kentdotn]

@googlebot I signed it!

[googlebot]

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

[johanbrandhorst]

Thanks for your contribution! Could you may add an example that shows how this fixes the generated comments? Could add two simple files to examples/internal/proto/examplepb and merge them with a command in the Makefile?

[kentdotn]

Could you may add an example

In this PR comment? OK, hold on, please.

Could add two simple files

You mean adding, say, a.proto and b.proto under examples/internal/proto/examplepb and then add one more target in the Makefile like

SWAGGER_EXAMPLES_MERGE=examples/internal/proto/examplepb/a.proto \
                     examples/internal/proto/examplepb/b.prot
$(EXAMPLE_SWAGGERSRCS_MERGE): $(SWAGGER_PLUGIN) $(SWAGGER_EXAMPLES_MERGE)
        protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(SWAGGER_PLUGIN) --swagger_out=logtostderr=true,allow_merge=true:. $(SWAGGER_EXAMPLES_MERGE)

Or is it suffice simply adding allow_merge=true to existing $(EXAMPLE_SWAGGERSRCS)?

[kentdotn]

Hmm... the patch works for my *.proto files, but it looks it doesn't help some other (rather simple) cases.
I'm digging into it further.

[johanbrandhorst]

Could you may add an example

In this PR comment? OK, hold on, please.

Could add two simple files

You mean adding, say, a.proto and b.proto under examples/internal/proto/examplepb and then add one more target in the Makefile like

SWAGGER_EXAMPLES_MERGE=examples/internal/proto/examplepb/a.proto \
                     examples/internal/proto/examplepb/b.prot
$(EXAMPLE_SWAGGERSRCS_MERGE): $(SWAGGER_PLUGIN) $(SWAGGER_EXAMPLES_MERGE)
        protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(SWAGGER_PLUGIN) --swagger_out=logtostderr=true,allow_merge=true:. $(SWAGGER_EXAMPLES_MERGE)

Or is it suffice simply adding allow_merge=true to existing $(EXAMPLE_SWAGGERSRCS)?

Lets add a new example as you suggest. Maybe name them something like swagger_merge_a.proto and swagger_merge_b.proto?

[kentdotn]

Ok, so I figured out what going wrong.
The code I posted solves a bug but there's another one.

The following might solve the other bug but I'm not sure this is no side effect.

diff --git a/protoc-gen-swagger/genswagger/template.go b/protoc-gen-swagger/genswagger/template.go
index da90927..27a8e76 100644
--- a/protoc-gen-swagger/genswagger/template.go
+++ b/protoc-gen-swagger/genswagger/template.go
@@ -1659,7 +1659,7 @@ func isProtoPathMatches(paths []int32, outerPaths []int32, typeName string, type
                        typeNameDescriptor = reflect.TypeOf((*pbdescriptor.DescriptorProto)(nil))
                }
 
-               if paths[0] != protoPathIndex(typeNameDescriptor, typeName) || paths[1] != typeIndex {
+               if paths[0] != protoPathIndex(typeNameDescriptor, typeName) {
                        return false
                }
                paths = paths[2:]

The problem is occurred because isProtoPathMatches doesn't care about typeIndex for merged target. Perhaps safer way to solve this is to have proper index for each method defined in a same svc.File.

What do you think of the snippet above? @johanbrandhorst

[kentdotn]

OK, the patch above doesn't work properly if you define two ore more services in one proto file.
Now I'll go the 'safer' way...

[kentdotn]

Could you may add an example

Added in PR comment.

Could add two simple files

Added.

[johanbrandhorst]

Thanks for your contribution! Could you cherry pick this against v2?

[kentdotn]

Alright, I'll push another one.