protoc-gen-openapiv2: Value comments appear in title instead of description

[davix]

🐛 Bug Report

The original discussion is in slack: https://gophers.slack.com/archives/CBATURP1D/p1651119673470069

To Reproduce

Given a proto

enum AEnum {
// a field comment
AENUM_UNSPECIFIED = 0;
}

Expected behavior

The a field comment should be in generated openapi's description field.

Actual Behavior

The comment is incorrectly in title field

Your Environment

macos, buf

[johanbrandhorst]

The easiest way to start working on a fix for this would be to create a failing test case. There are examples of tests lie this here: https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-openapiv2/internal/genopenapi/template_test.go. The logic for the comments is here: https://github.com/grpc-ecosystem/grpc-gateway/blob/8f476a01ac7beea62de7352fbc775245788bcfef/protoc-gen-openapiv2/internal/genopenapi/template.go#L771.

[mjnovice]

Hi, was wondering. Can someone on Windows dev machine attempt a fix for this ?

[johanbrandhorst]

There's no particular reason you'd need to fix this on Windows. If it's fixed it will be fixed on all platforms.

[mjnovice]

Sure, let me give this a shot!

[mjnovice]

@johanbrandhorst , @davix could you mention the command to reproduce the error ? Thanks.

[johanbrandhorst]

Hm, I went looking at our existing example enums: https://github.com/grpc-ecosystem/grpc-gateway/blob/963f1aa09bbbcf62bacdf2e3d0d6c45c3f76d7e4/examples/internal/proto/examplepb/a_bit_of_everything.proto#L417-L423. This is rendered like so: https://github.com/grpc-ecosystem/grpc-gateway/blob/963f1aa09bbbcf62bacdf2e3d0d6c45c3f76d7e4/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json#L4826-L4834. This includes all the comments in the description, and nothing in the title. Is this what you wanted @davix?

[davix]

could you remove the comment // NumericEnum is one or zero. and retry?

[marksartdev]

I have this problem, too.

[lachlancooper]

From what I can see this is due to the logic that decides whether to add a description and/or title, which depends partially on whether a comment ends in .: https://github.com/grpc-ecosystem/grpc-gateway/blob/6b2cf62b5e76379165000b914ef37afba9fd495c/protoc-gen-openapiv2/internal/genopenapi/template.go#L2048-L2049

Some speculation here, but it matches what I can see in a few of our generated specs:

• If the enum comment ends in ., the value comments are appended to the enum comment in description.
• If the enum comment doesn't end in ., it is set as title, and the value comments are appended to description.
• If the enum has no comment, the value comments will be appended to title or description depending on whether the individual value comments end in ..

[johanbrandhorst]

Haha that's well confusing, great digging @lachlancooper. I think we should definitely stop enum value comments from appearing in the title, that always seems wrong, with or without a full stop. The other behavior is sorta reasonable, but it would be great to document this in our docs: https://github.com/grpc-ecosystem/grpc-gateway/blob/master/docs/docs/mapping/customizing_openapi_output.md. So there seems to be two separate contributions here, that could be made together or not.

[wmvm0]

I have this problem, too.

me too