protoc-gen-swagger: add the package name to the tags field of each endpoint if the package name exists in the proto file

[zwcn]

Currently, given a path and a http method, there is no way to identify which package it is generated from. For example, since the following swagger file generated by protoc-gen-swagger contains only the service name dataService and the rpc name GetData, we can't derive the package name in the proto file that defines dataService and GetData.

{
  ...
  "paths": {
    "/api/v1/data": {
      "get": {
          "operationId": "GetData", // <--- the rpc name
          "tags": [
            "dataService" // <--- the service name
          ]
    }
  }
  ...
}

This pull request prepends the package name to the service name in the tags field. For example, if the proto file includes a line package data;, the tags field will be ["data.dataService"]. Doing this allows us to trace back the origin of the GET /api/v1/data http request.

[johanbrandhorst]

Hi again @zwcn. It looks like you need to regenerate the files after adding this fix. Please see the contribution guide for more information.

[johanbrandhorst]

Looks like we need to update some of the tests after this change:

examples/integration/client_test.go

https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/browser/echo_service.spec.js

[zwcn]

@johanbrandhorst , yes. As shown at https://github.com/grpc-ecosystem/grpc-gateway/pull/860/files#diff-eab1d67e52af78e98dd23e2b08fcc22aR25 , swagger-codegen generates go files based on the tags field of the input swagger file.

How do you feel about these long-name changes?

[johanbrandhorst]

Haha yeah I noticed. I suppose it's not wrong but they're not pretty names. I wonder if we can remove the tag from the generated names with a generator option? Please take a look.

[zwcn]

Hi @johanbrandhorst ,

Yes, the names aren't wrong. As shown at https://github.com/swagger-api/swagger-codegen/wiki/FAQ#how-do-tags-affect-the-generated-code, the tags filed is required for swagger-codegen to group APIs. So swagger-codegen did the right thing.

i've browsed the swagger-codegen docs. Unfortunately, I couldn't find any argument for swagger-codegen to ignore (or override) tags during code generation.

One possible solution would be to add a new boolean flag called allow_package_in_tags to protoc-gen-swagger. The package name is prepended only when it's true. This gives users more flexibility to have pretty names when they don't care about an API's origin at all.

How do you think?

[johanbrandhorst]

I think we're gonna have to add a flag as you say as this could be considered backwards compatibility breaking as well. Could you update the PR with a flag please? See if you could add some tests or a new file generated with the new flag as well please.

[zwcn]

@johanbrandhorst : Sounds like a plan. Will do.

[codecov-io]

Codecov Report

Merging #860 into master will decrease coverage by 0.07%.
The diff coverage is 35.71%.

@@            Coverage Diff             @@
##           master     #860      +/-   ##
==========================================
- Coverage   53.08%   53.01%   -0.08%     
==========================================
  Files          39       39              
  Lines        3888     3901      +13     
==========================================
+ Hits         2064     2068       +4     
- Misses       1630     1637       +7     
- Partials      194      196       +2

Impacted Files	Coverage Δ
protoc-gen-grpc-gateway/descriptor/registry.go	60.9% <0%> (-1.13%)	⬇️
protoc-gen-swagger/main.go	27.35% <50%> (+1.35%)	⬆️
protoc-gen-swagger/genswagger/template.go	53.48% <50%> (-0.07%)	⬇️

---

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 b7a5640...d423496. Read the comment docs.

[zwcn]

Hi @johanbrandhorst , I've added a new boolean flag allow_package_name_in_tags and some unit tests in main_test.go. Could you please take a look?

[johanbrandhorst]

Thanks a lot for your contribution!