openapiv2_tag.name does not work

[omrikiei]

🐛 Bug Report

openapiv2_tag name attribute is not being considered during generation

To Reproduce

1. Annotate with openapiv2_tag.name to a name different than the service's name
2. buf generate

Expected behavior

name should override the service name in swagger.json artifact.

Please assign this to me if possible - I'm working on a fix

Actual Behavior

Name doesn't change

Your Environment

[seanlaff]

Is there any additional config needed to make this work? I've been trying it with the latest release (2.19.1) and the tags in the methods don't seem to have the overridden name

syntax = "proto3";

package test;

import "google/api/annotations.proto";
import "protoc-gen-openapiv2/options/annotations.proto";

option go_package = "testing/test";

// ABitOfEverything service is used to validate that APIs with complicated
// proto messages and URL templates are still processed correctly.
service ABitOfEverythingService {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_tag) = {
    name: "ABitOfEverything"
    description: "ABitOfEverythingService description -- which should not be used in place of the documentation comment!"
    external_docs: {
      url: "https://github.com/grpc-ecosystem/grpc-gateway";
      description: "Find out more about EchoService";
    }
  };

  rpc CreateBody(CreateBodyRequest) returns (CreateBodyResponse) {
    option (google.api.http) = {
      post: "/v1/example/a_bit_of_everything"
      body: "*"
    };
  }
}
message CreateBodyRequest {}
message CreateBodyResponse {}

"tags": [
    {
      "name": "ABitOfEverything",
      "description": "ABitOfEverythingService description -- which should not be used in place of the documentation comment!",
      "externalDocs": {
        "description": "Find out more about EchoService",
        "url": "https://github.com/grpc-ecosystem/grpc-gateway"
      }
    }
  ],
  ....
        "tags": [
          "ABitOfEverythingService"
        ]

buf yaml:

version: v1
managed:
  enabled: true
plugins:
  - plugin: buf.build/grpc-ecosystem/openapiv2:v2.19.1
    out: openapi-spec

[johanbrandhorst]

Hm, perhaps there needs to be an additional fix to update the tags of the methods in the service? CC @omrikiei

[seanlaff]

Oh I understand the problem, it looks like #3843 didn't address the behavior in all scenarios (unsure if that was intentional due to limitations- or an oversight).

It looks like the tag is only being overridden if an RPC happens to have a non-nil openapiv2_operation annotation.

Here's an rpc that did properly get the tag overridden/inherited from its Service

grpc-gateway/examples/internal/clients/abe/api/swagger.yaml

Lines 1401 to 1405 in ffe8ce6

	/v1/example/a_bit_of_everything/query/{uuidName}:
	get:
	tags:
	- "ABitOfEverything"
	operationId: "ABitOfEverythingService_GetQuery"

and its corresponding proto definition

grpc-gateway/examples/internal/proto/examplepb/a_bit_of_everything.proto

Lines 585 to 595 in ffe8ce6

	rpc GetQuery(ABitOfEverything) returns (google.protobuf.Empty) {
	option (google.api.http) = {get: "/v1/example/a_bit_of_everything/query/{uuid}"};
	option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
	deprecated: true // For testing purposes.
	external_docs: {
	url: "https://github.com/grpc-ecosystem/grpc-gateway";
	description: "Find out more about GetQuery";
	}
	security: {}
	};
	}

and here's an rpc within the same service that didn't get the tag applied

grpc-gateway/examples/internal/clients/abe/api/swagger.yaml

Lines 4494 to 4498 in ffe8ce6

	/v1/{book.name}:
	patch:
	tags:
	- "ABitOfEverythingService"
	operationId: "ABitOfEverythingService_UpdateBook"

with its corresponding proto defintion

grpc-gateway/examples/internal/proto/examplepb/a_bit_of_everything.proto

Lines 525 to 530 in ffe8ce6

	rpc UpdateBook(UpdateBookRequest) returns (Book) {
	option (google.api.http) = {
	patch: "/v1/{book.name=publishers/*/books/*}"
	body: "book"
	};
	}

Do we think thats the desired behavior? If not, should we re-open this issue, or would it be better to create a new one @johanbrandhorst?

[johanbrandhorst]

This sounds like a bug, so I've reopened the issue. Thanks for digging into this!

[seanlaff]

I am looking into fixing this but Im having a lot of trouble figuring out how to run/test the openapi generator. If I want to regenerate a_bit_of_everything with my changes to the generator- what is the best way to do that?

[johanbrandhorst]

Please see the instructions in CONTRIBUTING.md, or if you have the tools installed locally you can just run make generate.