Add tags for OpenAPI endpoints

[YassineMEJRI]

Resolves #2716

[jdegoes]

I would have a preference to incorporate the concept of a tag in Doc, and then use the existing mechanism to add tags to the doc.

@987Nabil Any objections to that approach?

[987Nabil]

@jdegoes what I do not like about this is, that currently a doc is very explicitly instructions to render a doc. Tags would not be a part of the doc string generated for a path variable, for example. The concept of a tag exist only on the level of the endpoint. So I think this should be the only way it can be modeled. We could have a class that contains docs and tag and maybe more thing in the future (authentication requirements?) in the param of endpoint that is currently doc? 🤔

[987Nabil]

I just checked again for smithy. There it seems data structures can have tags too. But maybe such tags should go to the schema? 🤔

[YassineMEJRI]

It also seems that tags can be more than just strings and have optional attributes according to OpenAPI specification
How should this be handled? Should there be a Tag class?

[jdegoes]

@987Nabil I was thinking something like Doc.Tag(...) so it would have structure and be easy to use for OpenAPI generation. Of course, we could replace Doc by something that has both (current) Doc and Tags, but it seems to me any Tag can easily be render as HTML, plaintext, etc., so it could fit into existing Doc. Thoughts?

[987Nabil]

@YassineMEJRI lets give @jdegoes idea a try. Let's see how it looks like

[jdegoes]

@YassineMEJRI Please re-open when you get a chance to fix the build! 🙏