Solving the Issue of Swagger API Not Grouping Correctly in drf-yasg

Swagger is a very useful interactive documentation tool in backend development. Django's original Django-Swagger has stopped being maintained. Now people generally use the drf_yasg package to implement documentation. It supports both swagger and redoc. redoc is static, which is nice for exporting documentation, but we generally use swagger because you can debug inside the documentation, which is very convenient.

DRF has something called AutoSchema that can automatically scan places that provide APIs such as ViewSet and APIView. Unlike Spring's annotation-based documentation definition, in DRF you generally don't need to manually configure the name and description of each endpoint; just write them in the pydoc. However, this AutoSchema isn't very accurate either. It groups by URL, and especially with multi-level URLs like ours, it only groups by the first-level URL, so you get the ungrouped effect shown below.

Ungrouped Effect

Effect After Grouping

Solution

Define a class that inherits from SwaggerAutoSchema to customize the tags configuration, so we decide which level of the URL to use as the grouping tag.

Create a file, in this example: config/swagger.py

from drf_yasg.inspectors import SwaggerAutoSchema

class CustomSwaggerAutoSchema(SwaggerAutoSchema):
    def get_tags(self, operation_keys=None):
        tags = super().get_tags(operation_keys)

        if "v1" in tags and operation_keys:
            #  `operation_keys` 内容像这样 ['v1', 'prize_join_log', 'create']
            tags[0] = operation_keys[1]

        return tags

Then configure it in settings:

# Swagger 配置
SWAGGER_SETTINGS = {
    'DEFAULT_AUTO_SCHEMA_CLASS': 'config.swagger.CustomSwaggerAutoSchema',
}

That's all it takes~

References

• https://github.com/axnsan12/drf-yasg/issues/489

Welcome to Discuss

I've compiled a series of technical articles and materials. Reply with linux, flutter, c#, netcore, android, kotlin, java, python, etc. in the backend of the WeChat official account 「程序设计实验室」 to get related technical articles and materials. If you have any questions, you can also leave a message in the official account backend~