Add support for x-tagGroups

[steve-nay-sage]

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.

[steve-nay-sage]

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

[nikicc]

+1. x-tagGroups would be really handy 🙏

[mnaumanali94]

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: OAI/OpenAPI-Specification#1367

[steve-nay-sage]

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.

[TekExplorer]

x-tagGroups seems like the perfect solution. It would be incredibly useful to be able to group nested routes!

[anikitin]

Would be very-very helpful! IMHO, this is a must to compete with ReDoc

[ghost]

Hi. We have a need for x-tagGroups as well. Our documentation is quite large and many endpoints are only applicable to specific products/features. We have a mix of customers using different combinations of products, and some endpoints are applicable to multiple products, so we do want to have all endpoints defined in the same spec rather than in separate specs. We'd like to be able to group tags by product or similar so customers can expand/collapse the product areas they care about.

This is a big enough of a problem that we are looking at alternative tools, but would prefer to stay with RapiDoc. We need just one more level of hierarchy, which x-tagGroups provides.

[joel-maizonnier]

Hi. We have a need for x-tagGroups as well. Our documentation is quite large and many endpoints are only applicable to specific products/features. We have a mix of customers using different combinations of products, and some endpoints are applicable to multiple products, so we do want to have all endpoints defined in the same spec rather than in separate specs. We'd like to be able to group tags by product or similar so customers can expand/collapse the product areas they care about.

This is a big enough of a problem that we are looking at alternative tools, but would prefer to stay with RapiDoc. We need just one more level of hierarchy, which x-tagGroups provides.

Also in the same situatuion, we need this feature added to Stoplight.

[weyert]

I have it implemented. I am only not sure if Stoplight will accept the PR for it.

I was thinking to only use that approach when x-tagGroups exist otherwise fallback to the current existing behaviour.

[anikitin]

@weyert, this is a great news! Thank you for looking into this.

As a side not to your comment, it needs to be defined how it would work if not all tags belong to tag groups. Not sure what ReDoc does in this case, but there could be the following options:

• ignore x-tagGroups and behave as today if there are tags without groups
• Introduce an artificial "Other" group

[anatolii-balakiriev]

Any news on this? Would be great to have this functionality. We are in the middle of picking the right tool for us and this functionality is kind of a must have. Both Redoc and Scalar support that.

[weyert]

I have raised a PR for it

[anatolii-balakiriev]

@weyert it looks like some end to end tests failed in your PR: https://github.com/stoplightio/elements/pull/2603/checks
Are you aware of this?

[weyert]

Hmm, I will have a look. Last time I had trouble running these tests

[dnlsndr]

Yes, this would be super helpful