stoplightio
Add support for x-tagGroups
User story.
As a technical writer I want to be able to group OpenAPI tags under headings for better left-column navigation in API documentation.
Is your feature request related to a problem?
The development architecture that I work with creates different tags for every object type, such as customer, cart, order, etc. That would be manageable if there were only high-level objects like that, but our API is quite large and has many smaller objects that make up those high-level objects, such as customer-type and customer-contact-info. Those two examples would be tagged as customer-type and customer-contact-info. The devs are happy with their tagging style, especially because some of the lower-level objects are used by multiple higher-level objects. That kind of tagging doesn't make for good navigation in the left-column for documentation.
Describe the solution you'd like
Since I can't change the source material, I'd like to improve how it's handled in the documentation. Redoc supports a vendor extension named x-tagGroups that is used to group tags in the side menu. I've used it before and found it to be a very nice, simple enhancement to make navigation easier and documentation more useful. It would be great to see this extension supported in Elements.
Another way to do this might be with a clever handling of multiple tag values. If an operation has more than one tag, treat the first tag as a tag group and the second tag as an item within that group. For example, an operation tagged with
tags: [fruit, apples]
Would be sorted into the left-column TOC as
fruit apples
What do y'all think about handling it using dot operated tags. i.e. if the first tag is fruit.apples, would result in fruit -> apples as a nested group. Tags can be used for other things like discovery, search - so this would ensure not breaking it for other folks while allowing flexibility.
There's been some conversation around that here: https://github.com/OAI/OpenAPI-Specification/issues/1367
I would prefer a solution like x-tagGroups because it is specifically for documentation and would not affect other uses of tags. Code generators need to read the same OpenAPI files as documentation formatters, so whatever is done to enable grouping tags in documentation can't break how they're used by code generators. The use of multiple tags is already allowed by the OpenAPI spec, so code generators should already be able to handle that. Theoretically they should also be able to handle dot notation in tag names because it's a free-from string field, but I think dot notation is more likely to mess something up or be misinterpreted. The use of x-tagGroups avoids these potential problems.
x-tagGroups seems like the perfect solution. It would be incredibly useful to be able to group nested routes!
