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 #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

[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 😁 .

</HEADY PHILOSOPHY>

[hqsz]

Go up! plz add it 👍

[H0vo]

Almost 2024

[nathan-fiscaletti]

[olemoign]

I don't normally comment on this attitude, but I'm getting tired of the number of "+1", "need", "just get this done" messages.
You want it? Get to work, submit a PR. Stop complaining. You're asking for free work. You can do it too.

[Jend614]

Who is selling a book who is the Clint and who is the smaller and who is the amin

[Jend614]

I don't like seeing 1#0 #

[kamil-kielczewski]

I don't normally comment on this attitude, but I'm getting tired of the number of "+1", "need", "just get this done" messages. You want it? Get to work, submit a PR. Stop complaining. You're asking for free work. You can do it too.

@olemoign I actually like see "+1" "need" etc... because in issues ranking, when we sort by "most commented" this issue is higher and higher. Currently with 57 comment we are in TOP10 - I hope that this wil increase chaces that someone will implement it in future as important feature :)

https://github.com/OAI/OpenAPI-Specification/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc

[nathan-fiscaletti]

I don't normally comment on this attitude, but I'm getting tired of the number of "+1", "need", "just get this done" messages. You want it? Get to work, submit a PR. Stop complaining. You're asking for free work. You can do it too.

We're illustrating a desire for this to be implemented. There are maintainers that are actively contributing to this project, we're just trying to make it known that this is a feature we'd be very happy to see worked on.

[shybovycha]

I don't normally comment on this attitude, but I'm getting tired of the number of "+1", "need", "just get this done" messages. You want it? Get to work, submit a PR. Stop complaining. You're asking for free work. You can do it too.

It is not like there is no one trying. Over 3 years ago I made one to openapi-generators trying to address it and was told off and redirected here. So instead of adding a new issue I described my use case here and moved on without openapi.

Some maintainers are really conservative for a good reason - their open source projects are used by so many people that finding a middle ground on any opinion (or suggestion) is a tough battle. Think about changing C++ language specification and how long that takes. Similar problem here.

Luckily, there is (or at least should be) plugin API so can get it done some way or another.

[kael-shipman]

Note my comment here (specifically that this discussion is actually irrelevant to OAS and is more an implementation detail of the docs generators), and also that I've created a swagger plugin for this. See details on that plugin here under the "Edit: Permanent Solution" header of the issue description.

While it would be nice for OAS to explicitly mention tag hierarchies so as to "protect" them from future divergence among generators, it's not really necessary, and the absence of this in OAS is not really holding anything back.

[fedu]

+1

[Morta1]

+1

[lornajane]

There's a related discussion about tags for the next version of OpenAPI happening over here, in case anyone is interested OAI/sig-moonwalk#67

[mandos21]

I also support the request for sub-tagging. I was honestly very surprised to see this issue has been open for 5 years now, as it seems crucial for human readability and organization of documentation.

[hsynetal]

I agree with adding sub-tagging. I'm surprised this issue has been open for 5 years because it's important for making the documentation easier to read and organize.

[handrews]

@mandos21 @hsynetal the project kind of went into hibernation after 3.1, partially due to the pandemic. So things open at that time stayed open until recently, and now we are working on four releases (3.0.4, 3.1.1, 3.2.0, and 4.0 a.k.a. "Moonwalk"). Changes like this can't be incorporated until another minor release, so that means 3.2 which we'll look at after we get 3.0.4 and 3.1.1 out the door.

[kevinhuang-st]

I support having nested tags. It would be really nice to be able to have subgroups of endpoints.

[handrews]

I was honestly very surprised to see this issue has been open for 5 [EDIT: 7] years now, as it seems crucial for human readability and organization of documentation.

Keep in mind that between the time that this issue was filed and now, there has only been one non-patch OAS release (3.1). After that, a confluence of factors including the pandemic and the amount of time tooling vendors needed to support 3.1 put a lot of things on hold. I don't see any comment about why it didn't get into 3.1- probably because the Schema Object changes were already a lot, but there hasn't been another release where it could go until now.

We are finally starting to work on 3.2 in hopes of publishing it by the end of the year (that's my personal timeline, and not a commitment, but it will intentionally be much smaller than 3.1). Prior to 3.2, we had a lot of work to do to manage the backlog and put out 3.0.4 and 3.1.1 (which are in the final stages of pre-release now).

The resolution (for now) of the Moonwalk discussion @lornajane linked is that it could be done in 3.2, so I'm adding this issue to the 3.2 milestone.

[dima-dmytruk23]

+1

[EddLonzanida]

+1

[ReYaNOW]

+1

[darioamalfitano]

+1

[lornajane]

The proposal to add the ability to nest tags inside one another (and some other tag-related improvements) is now available for review. Please take a look at #4063 and give some feedback about whether those changes would meet the use cases you have in mind. This feature is tentatively planned for the next minor version release which will be 3.2.

[CryDevOk]