Multi-level (nested) tagging in Swagger UI

11,347

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

Share:
11,347

Related videos on Youtube

kani mozhi
Author by

kani mozhi

Updated on September 15, 2022

Comments

  • kani mozhi
    kani mozhi 3 months

    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?

  • user2122524
    user2122524 over 3 years
    Here is the conversation on this rquest: github.com/OAI/OpenAPI-Specification/issues/1367