Feature: sub-tags grouping

[kamil-kielczewski]

I don't know it is good place to introduce new Feature into swagger specification - if not please give me information where i can put this proposition.

My proposition is to use following convention in tags names (using dots to nesting subtags):

users.client     # and use this tag to client GET/POST/...
users.seller     # and use this tag to seller GET/POST/...
users.admin      # and use this tag to admin GET/POST/...
books            # use this to general books GET/POST...
books.sell       # use this to GET/POST... associated with the sell
books.management # use this to GET/POST... associated with the books management

And in output generated documentation web-page we will get:

user >
       client >
GET
POST
...
       seller >
GET
POST
...
       admin >
GET
POST
...

books >
GET
POST
...
       sell >
GET
POST
...
       management >
GET
POST
...

This feature is especially practical for large APIs.

Or may be better way is not change 'tags' but rather add new filed 'groups' which will contain such dot-separated nested groups?

[ymohdriz]

Hi @kamil-kielczewski

Adding the path level tagging solves the requirement, if I understood correctly. I have raised a PR https://github.com/OAI/OpenAPI-Specification/pull/1509 for the same.

Thanks, Mohammed

[maaland]

I support the request for a sub-tags. I want to be able to group (or at least sort) the methods under each of my endpoints, and as far as I can tell, that's not possible right now.

[jukeblimp32]

I support the request for sub-tags. Right now my tags are my collections. But with some collections exposing several different resources that can each support GET, PUT, and PATCH, the tags can become very cluttered. I want to be able have sub-tags for each resource within the collection tag.

[farmbotgianpaolo]

I support the request for sub-tags. I have a big API with tens of access points that need categories.

[anentropic]

This is one area where apib is better... there is a hierarchy like "Resource Group > Resource > Transition" where a Transition is roughly an OAS path and a Resource could be represented with an OAS tag.

For large APIs it would be useful to be able to group the endpoints at a level above single tags.

OAS is flexible enough I can represent this in the data with some combination of tags and extension properties, but for it to really be useful you would want a standardised representation that the tools such as Swagger UI then also support.

[amandajordaan]

I have a very large API to document, large with a very basic structure: API { Service 1 { Tool 1, Tool 2, Tool 3, (etc) } Service 2 (etc) { Tool 1, Tool 2, Tool 3, (etc) } ... } Being able to link one path to two tags and having them fall in a parent-child structure, would solve this problem. I have played around with the entire spec and it simply won't stretch to accommodate this API. Has this need been addressed yet? I find a great number of people needing this, but no answers on how to accomplish this yet - has anyone found a work-around on this limitation?

[darrelmiller]

We have an OpenAPI document that is 540K lines long https://github.com/microsoftgraph/msgraph-metadata/tree/master/openapi/beta We put dots in the tags and operations to create namespaces. I don't expect UI tools and code-generators to be able to handle specifications this size. I built a tool that splits OpenAPI documents based on tags and then feed the smaller docs to tools.

I don't think asking tooling to handle very large API descriptions is the right answer. Divide and conquer and split your API into smaller, more manageable chunks.

[ymhuang0808]

Hi @darrelmiller, Thanks for your experience. I would like to know if you could share the tool which splits the tags in OpenAPI documents.

[storm367]

Yes @darrelmiller pls do share what tool you used to create tag hierarchy

[darrelmiller]

The code for it is here https://github.com/darrelmiller/apislice/tree/master/apislice but I'm am working to move it into a command line tool that anyone will be able to use.

[shybovycha]

we have similar problem with OpenAPI as of now. feels like using tags approach is more of a workaround rather than a proper solution. would it be possible to have an extra parameter in specification (which can be later picked up by projects like openapi-generator) where users can define the resource name where method belongs? IMO this would be a better solution, since for tags it is possible that

a. multiple "resource-like" tags could be used for one method, effectively making it ambiguous behaviour b. tags are more informational than definitive data, does not feel like resource path should be defined

[jantuitman]

This issue is already more than 2 years old and my swagger UI page of current project is a big mess qua sorting, while the project is only small/medium sized. So doesn't look good. I saw some pretty low impact PR was being closed with argument "we need to know if existing workflows find this useful". In the same time there is a big PR with an unclear state to add many to many relationships and nested resources and that kind of stuff. But it looks big and complicated. So, wouldnt it be a great idea to have in the meantime a light weight iteration based on the tags? It would help my "existing workflow" for sure.

[kael-shipman]

I +1 this feature request, and put my vote behind the fully backward-compatible scheme in which tags remain a single string with the option of a special delimiter character to denote hierarchy (e.g., Main Tag|Sub Tag|Tertiary Tag). My preference is | or :, as these are common delimiter characters in other tagging schemes, but it looks like there's some momentum around ., and I would be happy with that as well.

It's fair to note that, given the above, this feature request is completely impertinent to OAS and is instead an implementation detail of docs viewers. Given that, it should be fairly simple for docs viewers to implement support for this post-hoc, so I'm personally going to go forward with using the scheme and encourage docs viewers to catch up.

[SteveNay-vz]

Tag names are hugely important when Swagger-Codegen creates client SDKs. For example, in a JavaScript client the tag names become class names. Any proposal for a feature that is mostly for doc viewers needs to also consider any implications for generated client SDKs.

[kael-shipman]

This is a very good point! It's certainly worth considering, although I would argue that the code generators may have taken some liberties in using what is technically a free-text string field for something so specific. This, of course, is the danger in including broad-purpose fields in a spec.

At any rate, it does seem like it would be worthwhile to include additional information about tags that could help both code generators and doc generators, and that information would probably be best captured in a Tag object.

Perhaps it could be as simple as adding an additional field, classname (or similar), in the Tab object specification that code generators can use to generate SDKs. Alternatively, code generators could either strip out non-alphanum characters or honor the hierarchy convention by dividing the SDK into subclasses according to the tag hierarchy.

I would think the latter would be the more appealing option, in which case this adds strength to the argument for hierarchicalizing tags.

[anentropic]

I haven't looked at them but surely the code generators must already be normalising and stripping invalid chars, and concatenating multiple tags, if they are using these as the basis of classnames in the clients... otherwise they're already broken, since it's already a free text field

[SteveNay-vz]

Yes, Codegen normalizes tag strings when creating client SDKs.

The issue that I was trying to raise is that OpenAPI definitions aren't used just to create API documentation; they are written in a machine-readable format so that code can be generated directly from the definition. Thus, any proposed changes need to work for these different purposes, or at least not get in the way.

[wvieed]

Waleed-131

[andre-dasilva]

whats the current state of this issue? will this be supported in the future?

[lonode]

Sub-tags would be especially useful for large API with larges paths and sub-paths. +1 For this feature request.

[nathan-fiscaletti]

I manage a lot of very large API's with a ton of endpoints. This feature would really benefit those projects greatly. Would love if it could get some attention :(

[kael-shipman]

If it's useful to you, I've published a swagger plugin for this. See discussion and link to the plugin here.

[ReivenIV]

Hi i see these forum is from 2017 and now sep2022... Did someone found a solution for these? is possible to do these in swaggerUI 3.0 ? Thanks

[jantuitman]

Hi i see these forum is from 2017 and now sep2022... Did someone found a solution for these? is possible to do these in swaggerUI 3.0 ? Thanks

I have a workaround but it requires work: build some custom code to grep all the elements from the json file which belong to a specific tag, and write them back in a separate json file. So i have multiple swagger docs for our 1 project.

[kael-shipman]

@ReivenIV I've published a Swagger plugin for this here. See additional discussions here.

[bhuvneshgalaxy]

Hey 2022 is also ending whats the current state of this issue? any solution ?

[amandeepnetweb]

I am also awating for the same. Someone please implement this feature.

[mankrit-singh]

Hey, requesting team to please implement this feature.

[dm-pr]

It's 2023 now... still no possibility to group tags .... as per this excelent proposal... what gives ?

[sc-ahn]

Hello from 2023 we need this feature but can't find any progress of this feature

[xuhuaiqu]

Hello from 2023。Any progress?

[sidneip]

I am following this issue with some hope.

[lanxin11]

Also following up on this issue and hoping to understand where we're up to regarding this feature.

[eL1fe]

Hi, I'm from the future, from 2025, they finally added this feature, just wait and hope 😎

[MikeRalphson]

@eL1fe please keep comments considerate. We do have a code of conduct.

[nop1984]

Hi, I'm from the future, from 2025, they finally added this feature, just wait and hope 😎

@eLfe can you drop code.zip here?

[spuxx1701]

Need!

[Davidos533]

It's cool and needed

[RodionKorneev]

+1

[int-maxd]

Please add it

[jhleung]

add

[kabalan-datapostie]

+1

[mtorre-SH]

+1

[brunotacca]

+1

[qbecb1zen]

+1

[oskarbet]

+1

[justachamp]

+1

[cengler69]

+1

[darrelmiller]

If anyone is curious, this conference talk addresses how we handle large and deeply nested APIs https://www.youtube.com/watch?v=9Fvt3QzMI34

TL;DR - The path is already a hierarchy, use that to organize your devX experiences instead of trying to create a second hierarchy.

[kael-shipman]

\<HEADY PHILOSOPHY>

I like that idea in theory. I just watched the talk and totally agree with everything you've said in it - that's exactly the way I personally go about designing my APIs!

However, I also think it's important to provide tools for the more common case when you haven't played the perfect game of chess - meaning, that there was something 30 moves ahead that you missed when you were first designing your API and now you have to live with it. This is an everyday reality for myself and I think for most people. Not to mention the also quite common case when you take custody of a legacy API and need to document it during a transitional period (which, like it or not, can often last years).

In these cases, I think it's important to be able to utilize discretionary structures like hierarchical tags to force things into an organizational structure that's more reflective of the current understanding than the actual underlying implementation may be. In the end, you can always (and should!) just name your tag hierarchy after your URI components if you did happen to get it right.

So I guess my vote is this: OAS, as a neutral tool, should provide structures for developers to use that acommodate the realities of their world, however messy that world may be; and developers, for their part, should strive to be intentional about their information architecture such that their URIs are as self-documenting as possible. Art, meet craft :grin: .

</HEADY PHILOSOPHY>