Multi-level (nested) tagging in Swagger UI

Question

I just started working on Swagger 2.0 API recently. I am looking for some ways to organize the API documentation.

Currently I'm using the @Api(tags = {"Heading1"}) Java annotation to tag each API. The generated documentation looks like

Tasks
--------->Heading1
          -------->Desc1
          --------->Desc2
---------->Heading2
          --------->Desc3
          --------->Desc4

I'd like to add some subheadings in the doc, so that it looks like

Tasks
--------->Heading1
          -------->Desc1
          --------->SubHeading1
                        --------->Desc2
---------->Heading2
          --------->SubHeading1
                     --------->Desc3 
          --------->SubHeading1
                     --------->Desc4

How do I achieve this?

Solution

Nested tags are not supported by the OpenAPI Specification. Here's the corresponding feature request:
https://github.com/OAI/OpenAPI-Specification/issues/1367

You can try to emulate nested tags by naming your tags tag1/tag2, tag1.tag2, tag1|tag2 or similar, but then you'd also have to modify your tools to handle such names as nested tags.

Note for Swagger UI users: There's a feature request to support nested tags using tag names in the form tag1|tag2 or similar:
https://github.com/swagger-api/swagger-ui/issues/5969

Comments

[user2122524]

Here is the conversation on this rquest: github.com/OAI/OpenAPI-Specification/issues/1367