Support Hierarchical Tags

[kael-shipman]

Is your feature request related to a problem?

There is growing support in the OAS community for the idea of hierarchical tags (see OAI/OpenAPI-Specification#1367). The current consensus is that UIs like SwaggerUI can implement this with no change required in the OAS, and that this would be a much appreciated feature. I would like to implement it in SwaggerUI and would like help identifying the best way to do so.

Describe the solution you'd like

Tags such as Petstore|Mammals|Dogs should render as

## Petstore

### Mammals

#### Dogs

....

EDIT: Temporary Solution

I've implemented and published a package for this. Instructions for use are here. There is also a PR out for this (here), but it is long stale and I doubt that Swagger will ever take interest in it. For now, your best bet is to use my published package, which works well as an ES module include in a webpack scenario OR as a global module via unpkg.

[kael-shipman]

I'm willing and able to implement this, even if just for my own fork of SwaggerUI, so regardless of whether this feature gets official approval or not, I'd love for someone to give me a hint at where to start.

[MarcusBondezan]

This would be great! The doc would be much more organized for the front end folks of my project.

[kael-shipman]

Thanks for commenting! Good to know others find this desirable.

To the devs: I repeat my offer to implement this and PR it if you'll give me a push to start me in the right direction ;).

[effrafax]

Yes, would be great to have such a feature!

[SaiSrinivasM]

Yes, I am also looking for the same

[leandrofnunes]

It'd be awesome to have such feature available - as of now, I need to create composed tags which causes lots of duplicates.

[donaldduy-lb]

I would also love this feature!

[daveKoala]

I am also looking for the same thing. My use case is, I have an existing API with 2 versions, about to start on the third, consumers add a field in the header asking for specified version. I think sub or hierarchical tags would make life so much easier for developers and readers of the docs. As i need to keep all versions in a single doc

Happy to be told that header accept version can be documented in a different manner

[mairead]

We need this feature too. Our API serves several products but also we have utility endpoints, global endpoints and product specific endpoints. It would be really helpful to be able to add sub headings and also even a description to each sub heading so you could explain the purpose of the grouping

[arkanmgerges]

Yes it is a good feature

[jwpegram]

Any movement on this feature?

[mathis-m]

@kael-shipman you could probably just override the component https://github.com/swagger-api/swagger-ui/blob/master/src/core/components/operation-tag.jsx using the plugin api. https://swagger.io/docs/open-source-tools/swagger-ui/customization/plugin-api/

then implement recursive rendering of the operation-tag within the render function of the component.

[kael-shipman]

@mathis-m thanks for the specific tip and documentation! Very helpful. I'm a bit swamped at work right now, but I'll look into maybe building a plug-in for this when I get a chance.

[mathis-m]

@kael-shipman for the plugin part I would use the wrapComponents plug point to conditional render either the hirachical operation tag component or the original component.

[kael-shipman]

Hi to everyone following this. Any thoughts on styling? This is what it looks like so far:

I tried left-justifying, too, but that made the hierarchy significantly less useful. Open to suggestions. If anyone's a whiz with this kind of stuff (css, react, etc.), feel free to PR my PR over at kael-shipman/swagger-ui-plugins@hierarchical-tags

[kael-shipman]

Also, if anyone's really itchin' to get this going on their site, I just published the pre-release (v1.0.0-rc1) on github packages. You can get it by doing the following:

1. Add @kael-shipman:registry=https://npm.pkg.github.com/kael-shipman to your package-local .npmrc file.
2. Run npm install --save @kael-shipman/swagger-ui-plugin-hierarchical-tags
3. Follow instructions in README.md

I believe that will work, but if it doesn't, I'd be happy to work through it with you.

EDIT: If you don't already have github authentication set up for npm, you have to do that as well:

1. Create a github personal access token for your account (tutorial)
2. Add //npm.pkg.github.com/:_authToken=YOUR-TOKEN to your user-specific .npmrc file (the one at ~/.npmrc, not the one in your package. If that file doesn't exist, then create it.) Make sure to put the value of your token in instead of the string YOUR-TOKEN.

[mathis-m]

@kael-shipman let's make this a PR against swagger-ui. I can give you guidance, let's connect to get this going!

[dmrickey]

Hi to everyone following this. Any thoughts on styling? This is what it looks like so far:

I tried left-justifying, too, but that made the hierarchy significantly less useful. Open to suggestions. If anyone's a whiz with this kind of stuff (css, react, etc.), feel free to PR my PR over at kael-shipman/swagger-ui-plugins@hierarchical-tags

At least in the APIs I work with, this could still be very long. It'd be nice to have some kind of vertical gray line on the left to signify how deeply something is nested.

[mathis-m]

At least in the APIs I work with, this could still be very long. It'd be nice to have some kind of vertical gray line on the left to signify how deeply something is nested.

How about:

[kael-shipman]

Love it! That looks great!

[kael-shipman]

@tim-lai, @mathis-m and I are working on a PR to swagger-ui to address this issue and we've run into some questions:

First, are you interested in this being part of swagger-ui? If not, we can stick to the plugin approach already mentioned above.

Second, if it seems acceptable for swagger-ui, what is your preferred architecture? I've implemented it as a backward-compatible core addition in this branch, but @mathis-m has suggested it may be more appropriate to build it as a core plugin, which he's started working on in this branch. I think either way is fine for us, but we'd like guidance before investing too much in one direction or the other.

[mathis-m]

In addition specification wise we are good to implement it.

Tagged operations may be handled differently by tools and libraries. For example, Swagger UI uses tags to group the displayed operations.

[JAdamCain]

I desperately need this functionality now. I'm a novice but willing to try it . Is it available as a plug-in I can just drop in. Corporate frowns on unofficial versions of major software but plug-ins are fair game!

[kael-shipman]

Yes, this is available as a plugin in at least a rudimentary form. See instructions up the page.

I think the only thing that doesn't have is the nice styling that @mathis-m brought to it. @mathis-m , and chance you could backport your styling to the plugin version of this, while they're sitting on our PR over there at the main project?

[mathis-m]

@kael-shipman I don't think we are able to integrate the styling like shown in my comment anyhow I will try to catch up on the PR in the next days and create needed tests for it hopeful we have this feature soon.

[JAdamCain]

Let me preface this by saying this is a dumb question but I'm trying to figure out how so many swagger sites have "Show/Hide" "List Operations" and "Expand Operations" at each tag but mine doesn't. is there some simple attribute that I'm missing or what... I can't find the answer anywhere

[mathis-m]

Let me preface this by saying this is a dumb question but I'm trying to figure out how so many swagger sites have "Show/Hide" "List Operations" and "Expand Operations" at each tag but mine doesn't. is there some simple attribute that I'm missing or what... I can't find the answer anywhere

Can you give us some context probably Screenshot and spec used?

[JAdamCain]

@mathis-m - thank you for offerign to help. Here is an example of those hyperlink/buttons on a public website https://transport.tamu.edu/BusRoutesFeed/swagger/ui/index#/ Routes has multiple methods under it so it does a good job of illustrating what those 3 actions do. and then my own site is at https://pricing.smc3.com/RateWarePlus/api/ i would like to have the api tag and others in the future use those same buttons. I have searched google like crazy and know I am probably missing some easy feature to turn or a plugin to add but I cannot find it. I am using OAS3. our tech stack includes Java 11, Tomcat 9, and Spring Boot 4.3(I think that's the right version number)

[mathis-m]

@JAdamCain Actualy the difference you are experiencing is due to major version difference of swagger-ui package used.

[JAdamCain]

@mathis-m - Thx I will get with developers on team about updating swagger-ui package Thanks!