Experience Summary: Customizing a Few Details of drf-yasg API Documentation

drf-yasg is an extension for Django REST Framework that can generate OpenAPI interfaces from routes. Using it, however, is quite different from Java platforms and .NET Core, and some customizations are rather cumbersome. Still, looking at the docs is fine enough, and you can get things working.

This article records a few issues encountered in actual development. Although they are details, polishing these details can make things much more convenient for colleagues integrating with the APIs~

By the way, writing backends in Python is really fast—can you believe dozens of APIs in one morning?

Setting Request Parameters and API Descriptions

Implementation Code

@swagger_auto_schema(request_body=openapi.Schema(
    type=openapi.TYPE_OBJECT,
    required=['phone'],
    properties={'phone': openapi.Schema(type=openapi.TYPE_STRING)}
), operation_summary='更新手机号码')
@action(detail=True, methods=['PUT'], permission_classes=[permissions.IsAuthenticated])
def phone(self, request, pk=None):
    """更新手机号码"""
    if request.method == 'POST':
        phone_num = request.data.get('phone')
        profile_obj: UserProfile = get_object_or_404(UserProfile.objects.all(),
                                                     user=request.user)
        profile_obj.phone = phone_num
        profile_obj.save()
        return Response({'detail': '更新手机号成功'})

Result

References

• Official documentation https://drf-yasg.readthedocs.io/en/stable/_modules/drf_yasg/inspectors/query.html?highlight=openapi.Parameter
• GitHub issues https://github.com/axnsan12/drf-yasg/issues/280

Adding a Description to Each Group

drf-yasg does not support this feature by default. This is a solution I found while browsing Stack Overflow—a bit of a roundabout workaround...

The Default State Looks Like This

Code

class CustomOpenAPISchemaGenerator(OpenAPISchemaGenerator):
    """重写 OpenAPISchemaGenerator 实现每个tag的说明文本"""

    def get_schema(self, request=None, public=False):
        swagger = super().get_schema(request, public)

        swagger.tags = [
            {
                "name": "core",
                "description": "核心功能",
            },
            {
                'name': 'external_units',
                'description': '外部单位'
            },
            {
                'name': 'field_investigation',
                'description': '现场勘查'
            },
            {
                'name': 'require',
                'description': '需求'
            },
            {
                'name': 'require_delivered',
                'description': '需求分配'
            },
            {
                'name': 'scheme_appraisal',
                'description': '方案评审'
            }
        ]

        return swagger

Result After the Change

References

• https://stackoverflow.com/questions/62572389/django-drf-yasg-how-to-add-description-to-tags