feat: add option to add description to tags

[same-id]

References to other Issues or PRs

Have you read the Contributing Guidelines?

Yes

Brief description of what is fixed or changed

Adding option to add description to tags by allowing specifying openapiv2 tags

Other comments

[johanbrandhorst]

Hi, thanks for your PR! This looks pretty neat to me, almost deceptively so. I'm going to rope in @ivucica for his thoughts on the changes since he's the original author.

[johanbrandhorst]

Looks like we ran into some CI errors

[same-id]

Hmm, seems like lint failed on removal of reserved fields, that is the correct process for that? Isn't it supposed to fail?

[johanbrandhorst]

I would ignore that lint error, we can merge over it. Your change looks right to me. The error here assumes that the field number was reserved because it has been removed (https://docs.buf.build/breaking/rules#reserved_message_no_delete), which is not the case here.

[same-id]

Cool, committed the suggestion as well

[kkolur]

Thanks @same-id for this great work!

@johanbrandhorst can we add extensions to the Tag object as well, maybe in a separate PR?

[johanbrandhorst]

@johanbrandhorst can we add extensions to the Tag object as well, maybe in a separate PR?

I think this'd have to start as a separate issue since it's pretty broad scope, could you create one?

[kkolur]

@johanbrandhorst can we add extensions to the Tag object as well, maybe in a separate PR?

I think this'd have to start as a separate issue since it's pretty broad scope, could you create one?

Created issue here

[kkolur]

@same-id @johanbrandhorst what would happen in the case a user defines their own tags at root level of open api object but dont disable the default rendering of service tags? Would the user defined tags override the default service tag generation, or does it get appended to it? How should this work?

[johanbrandhorst]

@same-id @johanbrandhorst what would happen in the case a user defines their own tags at root level of open api object but dont disable the default rendering of service tags? Would the user defined tags override the default service tag generation, or does it get appended to it? How should this work?

The example added here already shows what happens - the tags are simply appended to the end of the service tags.

[johanbrandhorst]

Please rebase/merge on master and regenerate.

[same-id]

After I regenerate I'm having lots of unrelated swagger-codegen diffs, not sure why:

-                  "$ref": "#/definitions/examplepbNumericEnum"
+                  "$ref": "#/definitions/examplepbNumericEnum",
+                  "description": "Numeric enum description.",
+                  "title": "Numeric enum title"
                 },
                 "repeatedStringAnnotation": {
                   "type": "array",
@@ -2358,7 +2360,9 @@
                   "title": "Repeated nested object title"
                 },
                 "nestedAnnotation": {
-                  "$ref": "#/definitions/ABitOfEverythingNested"
+                  "$ref": "#/definitions/ABitOfEverythingNested",
+                  "description": "Nested object description.",
+                  "title": "Nested object title"
                 },

Can you try and execute swagger-codegen (version 2.4.8) on master and check if it's not in sync?

[johanbrandhorst]

You need to reinstall the plugin again, there was a change in the latest PR. Run make install before running the regeneration command.

[johanbrandhorst]

LGTM, and I chatted with @ivucica about this change, he's happy too.

[same-id]

Rebased

[kkolur]

@same-id can we get this over the hump? I have an issue that depends on changes here and would love to get started on that. Great work btw!

[johanbrandhorst]

This failure is an expected false positive, I will merge as-is.

[johanbrandhorst]

Thanks for your contribution @same-id!

[same-id]

Is there a community for grpc-gateway?
I would love to ask some general questions (mainly regarding integrations with redoc) and not sure where it's best to have that discussion.

[adambabik]

@same-id join Gophers Slack and find the grpc-gateway channel. I think that's the most active community currently.