Drf-yasg: Rendering of nested routers in GUI

[gertjanol]

I stumbled upon this project when searching for documentation tools with support for nested routers. The example that you supply with the articles/{slug}/image is exactly what we use a lot in one of our API's.

In our case, we have several of these endpoints and in most cases each endpoint accepts 4 or 5 HTTP methods. So in the GUI, this is rendered as a huge list of endpoints, which is hard to work with.

Is there a way to group these endpoints as nested collections? So in your example, the image would get it's own heading, just like articles and snippets, but with a title like articles > images.

I hope my question makes sense. If you need more info please let me know.

[axnsan12]

The visual groups in the UI are created by applying a tag to operation objects. Unfortunately for your question, no, it is not possible to get Swagger UI to visually nest tags.

You could hack it by creating nested tag names, for example applying a tag named "articles > images" to the desired endpoints. This would then be shown after the "articles" group provided you sort the tags alphabetically in the UI (which is configured by default in the version distributed with this library).

However you would have to semi-manually implement that functionality, since it is not provided out of the box. My first idea for implementing it would go to subclassing SwaggerAutoSchema#get_tags() to switch the tag based on the operaion_keys hierarchy.

[axnsan12]

Since there is no concrete issue, and lacking any follow-up response, I'm going to close this as answered. Feel free to post further replies if anything remains problematic.

[gertjanol]

Hi @axnsan12,

Thanks for the hints! I managed to get things the way I imagined, thanks to your pointers. Turned out it's easier than I (and you? :)) thought, but I may have overlooked something. I did this:

# myproject/settings.py
SWAGGER_SETTINGS = {
    'DEFAULT_AUTO_SCHEMA_CLASS': 'myproject.swagger.CompoundTagsSchema',
}

# myproject/swagger.py
from drf_yasg.inspectors import SwaggerAutoSchema

class CompoundTagsSchema(SwaggerAutoSchema):

    # See https://github.com/axnsan12/drf-yasg/issues/56
    def get_tags(self, operation_keys):
        return [' > '.join(operation_keys[:-1])]

This results in these tags in the redoc-renderer:

I haven't tested other UI renderers, so maybe there are some gotcha's there?

[axnsan12]

Happy you got what you wanted 😁

[sylvainblot]

There is still an issue with nested router provided by: https://github.com/alanjds/drf-nested-routers
redefining get_tags properly classify the endpoints group, but the doc is not displayed correctly:

• in redoc nested method such as POST don't include the example payload.
• in swagger nested method such as POST don't include the example payload but you can find it in gray at the end of the page.