Error generating summary and description with use_go_templates=true

[tombracho]

📚 Documentation

Hello! First of all, thanks for your awesome plugin! 🎉

I'm trying to generate summary and description using information from the documentation:
customizing_openapi_output.md#using-go-templates-in-proto-file-comments

However, after generating OpenAPI v2 documentation, part of the description is incorrectly included in the summary field.

Expected behavior:

• The summary field should contain only the method name or the first line of the annotation.
• The description field should include the detailed method explanation and Markdown tables.

Actual behavior:

• summary contains too much information, including:
  ** Repeated method name.
  ** Full method description.
  ** Markdown tables (imported from tables.md).
• description is incomplete and missing part of the intended content.

Example of Incorrect Output:

  "paths": {
    "/api/volunteering/event/{id}": {
      "get": {
        "summary": "GetEvent\r\n\r\nGetEvent is a call with the method(s) GET within the \"VolunteeringHttp\" service.\r\nIt takes in \"EventId\" and returns a \"Event\".\r\n\r\n## EventId\n| Field ID    | Name      | Type                                                       | Description                  |\n| ----------- | --------- | ---------------------------------------------------------  | ---------------------------- | \n| 1 | id | TYPE_INT32 |  |",
        "description": "## Event\n| Field ID    | Name      | Type                                                       | Description                  |\n| ----------- | --------- | ---------------------------------------------------------- | ---------------------------- | \n| 1 | id | TYPE_INT32 |  | \n| 2 | creator_id | TYPE_INT32 |  | \n| 3 | title | TYPE_STRING | Заголовки | \n| 4 | og_title | TYPE_STRING |  | \n| 5 | description | TYPE_STRING | Описание | \n| 6 | og_description | TYPE_STRING |  | \n| 7 | content | TYPE_STRING | Контент | \n| 8 | address | TYPE_STRING | Адрес и город | \n| 9 | city | TYPE_INT32 |  | \n| 10 | organization_id | TYPE_INT32 | Идентификатор организации | \n| 11 | is_published | TYPE_BOOL |  | \n| 12 | eventDays | []TYPE_MESSAGE | Дни проведения эвента | \n| 13 | images | TYPE_MESSAGE | Изображения эвента | \n| 14 | directionIds | []TYPE_INT32 | Направления (идентификаторы) |",
        "operationId": "VolunteeringHttp_GetEvent",
    }
  }
}

Configuration:

buf.gen.yaml

version: v1
plugins:
  - name: go
    out: gen/protos/go
    opt: paths=source_relative
  - name: go-grpc
    out: gen/protos/go
    opt:
      - paths=source_relative
  - name: grpc-gateway
    out: gen/protos/go
    opt:
      - paths=source_relative
  - name: openapiv2
    out: swagger-ui
    opt:
      - allow_merge=true
      - merge_file_name=openapi
      - use_go_templates=true
      - openapi_naming_strategy=simple
      - disable_default_errors=true

And the .proto service definition:

service VolunteeringHttp {
  // GetEvent
  //
  // {{.MethodDescriptorProto.Name}} is a call with the method(s) {{$first := true}}{{range .Bindings}}{{if $first}}{{$first = false}}{{else}}, {{end}}{{.HTTPMethod}}{{end}} within the "{{.Service.Name}}" service.
  // It takes in "{{.RequestType.Name}}" and returns a "{{.ResponseType.Name}}".
  //
  // {{import "tables.md"}}
  rpc GetEvent(volunteering_service.EventId) returns (volunteering_service.Event) {
    option (google.api.http) = {
      get: "/api/volunteering/event/{id}"
    };
  }
}

And the tables.md

## {{.RequestType.Name}}
| Field ID    | Name      | Type                                                       | Description                  |
| ----------- | --------- | ---------------------------------------------------------  | ---------------------------- | {{range .RequestType.Fields}}
| {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}}

## {{.ResponseType.Name}}
| Field ID    | Name      | Type                                                       | Description                  |
| ----------- | --------- | ---------------------------------------------------------- | ---------------------------- | {{range .ResponseType.Fields}}
| {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}}

[johanbrandhorst]

I'm not sure what's going wrong here, could you perhaps create a repo that reproduces this issue? I haven't used it myself, but we do have a test proto that uses this option and seems to render correctly:

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

Lines 9 to 29 in 9fd8eba

	service LoginService {
	// Login
	//
	// {{.MethodDescriptorProto.Name}} is a call with the method(s) {{$first := true}}{{range .Bindings}}{{if $first}}{{$first = false}}{{else}}, {{end}}{{.HTTPMethod}}{{end}} within the "{{.Service.Name}}" service.
	// It takes in "{{.RequestType.Name}}" and returns a "{{.ResponseType.Name}}".
	//
	// ## {{.RequestType.Name}}
	// | Field ID | Name | Type | Description |
	// | ----------- | --------- | --------------------------------------------------------- | ---------------------------- | {{range .RequestType.Fields}}
	// | {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}}
	//
	// ## {{.ResponseType.Name}}
	// | Field ID | Name | Type | Description |
	// | ----------- | --------- | ---------------------------------------------------------- | ---------------------------- | {{range .ResponseType.Fields}}
	// | {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}}
	rpc Login(LoginRequest) returns (LoginReply) {
	option (google.api.http) = {
	post: "/v1/example/login"
	body: "*"
	};
	}

grpc-gateway/examples/internal/proto/examplepb/use_go_template.swagger.json

Lines 21 to 22 in 9fd8eba

"summary": "Login",

"description": "Login is a call with the method(s) POST within the \"LoginService\" service.\nIt takes in \"LoginRequest\" and returns a \"LoginReply\".\n\n## LoginRequest\n| Field ID | Name | Type | Description |\n| ----------- | --------- | --------------------------------------------------------- | ---------------------------- | \n| 1 | username | TYPE_STRING | The entered username | \n| 2 | password | TYPE_STRING | The entered password | \n\n## LoginReply\n| Field ID | Name | Type | Description |\n| ----------- | --------- | ---------------------------------------------------------- | ---------------------------- | \n| 1 | message | TYPE_STRING | | \n| 2 | access | TYPE_BOOL | Whether you have access or not |",

[tombracho]

I was reproduced the issue. You can find the code in this repository: https://github.com/tombracho/grpc-gateway-issue/tree/main.

The proto file in proto/userservice/
The generated open api spec is in proto/swagger-ui/

You can generate its again using command in makefile

And a i have this versions of plugin:

protoc-gen-go v1.36.5

protoc-gen-openapiv2 --version
Version v2.26.2, commit unknown, built at unknown

protoc-gen-grpc-gateway --version
Version v2.26.2, commit unknown, built at unknown

protoc-gen-go --version
protoc-gen-go v1.36.5

[johanbrandhorst]

I checked out this repo, ran make generate and it generated correctly:

diff --git a/proto/swagger-ui/openapi.swagger.json b/proto/swagger-ui/openapi.swagger.json
index 0abf56e..b5aa1de 100644
--- a/proto/swagger-ui/openapi.swagger.json
+++ b/proto/swagger-ui/openapi.swagger.json
@@ -23,7 +23,8 @@
   "paths": {
     "/api/user/{id}": {
       "get": {
-        "summary": "Login\r\n\r\nLogin is a call with the method(s) GET within the \"VolunteeringHttp\" service.\r\nIt takes in \"UserId\" and returns a 
\"User\".\r\n\r\n## UserId\r\n| Field ID    | Name      | Type                                                       | Description                  |\r\n| ----------- | --------- | ---------------------------------------------------------  | ---------------------------- | \r\n| 1 | id | TYPE_INT32 |  | \r\n\r\n## User\r\n| Field ID    | Name      | Type                                                       | Description                  |\r\n| ----------- | --------- | ---------------------------------------------------------- | ---------------------------- | \r\n| 1 | id | TYPE_INT32 |  | \r\n| 2 | email | TYPE_STRING |  | \r\n| 3 | first_name | TYPE_STRING |  | \r\n| 4 | last_name | TYPE_STRING |  | \r\n| 5 | phone | TYPE_STRING |  | \r\n| 6 | avatar | TYPE_STRING |  | \r\n| 7 | city | TYPE_STRING |  | \r\n| 8 | address | TYPE_STRING |  | \r\n| 17 | updated_at | TYPE_MESSAGE |  |",
+        "summary": "Login",
+        "description": "Login is a call with the method(s) GET within the \"VolunteeringHttp\" service.\nIt takes in \"UserId\" and returns a \"User\".\n\n## UserId\n| Field ID    | Name      | Type                                                       | Description                  |\n| ----------- | --------- | ---------------------------------------------------------  | ---------------------------- | \n| 1 | id | TYPE_INT32 |  | \n\n## User\n| Field ID    | Name      | Type                                                       | Description                  |\n| ----------- | --------- | ---------------------------------------------------------- | ---------------------------- | \n| 1 | id | TYPE_INT32 |  | \n| 2 | email | TYPE_STRING |  | \n| 3 | first_name | TYPE_STRING |  | \n| 4 | last_name | TYPE_STRING |  | \n| 5 | phone | TYPE_STRING |  | \n| 6 | avatar | TYPE_STRING |  | \n| 7 | city | TYPE_STRING |  | \n| 8 | address | TYPE_STRING |  | \n| 17 | updated_at | TYPE_MESSAGE |  |",
         "operationId": "VolunteeringHttp_Login",
         "responses": {
           "200": {

I think maybe you have two different versions of protoc-gen-openapiv2 installed? In any case, I can't reproduce this.