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.