如何在Swagger UI中展示Django DRF各API端点的权限？

drf-spectacular的@extend_schema装饰器默认没有内置的permissions参数，但可以通过自定义扩展来实现权限信息的展示，以下是具体实现步骤：

1. 自定义Schema扩展类 #

创建一个扩展类，用于提取权限信息并将其注入到Swagger文档中。该类可以从装饰器的自定义参数或视图本身的权限类中获取权限信息：

from drf_spectacular.extensions import OpenApiExtension

class PermissionSchemaExtension(OpenApiExtension):
    target_class = 'rest_framework.views.APIView'
    priority = 1

    def extend_schema(self, schema, view, **kwargs):
        # 优先获取@extend_schema中传入的permissions参数
        permissions = kwargs.get('permissions', [])
        
        # 如果装饰器未传，则从视图的permission_classes中提取权限类名称
        if not permissions and hasattr(view, 'permission_classes'):
            permissions = [perm.__name__ for perm in view.permission_classes]
        
        # 将权限信息添加到接口描述中
        if permissions:
            permission_text = f"\n\n**所需权限**: {', '.join(permissions)}"
            if schema.get('description'):
                schema['description'] += permission_text
            else:
                schema['description'] = permission_text.strip()
        
        return schema

如果需要适配函数视图，可以新增如下扩展类：

class FunctionViewPermissionExtension(OpenApiExtension):
    target_class = 'rest_framework.decorators.api_view'
    priority = 1

    def extend_schema(self, schema, view, **kwargs):
        permissions = kwargs.get('permissions', [])
        # 从函数视图的permission_classes装饰器中提取
        if not permissions and hasattr(view, 'permission_classes'):
            permissions = [perm.__name__ for perm in view.permission_classes]
        
        # 同类视图的处理逻辑
        if permissions:
            permission_text = f"\n\n**所需权限**: {', '.join(permissions)}"
            if schema.get('description'):
                schema['description'] += permission_text
            else:
                schema['description'] = permission_text.strip()
        
        return schema

2. 配置扩展类 #

在项目的settings.py中，将自定义扩展加入drf-spectacular的配置：

SPECTACULAR_SETTINGS = {
    # 其他原有配置...
    'EXTENSIONS': [
        'your_app.path.to.PermissionSchemaExtension',
        'your_app.path.to.FunctionViewPermissionExtension',  # 适配函数视图时添加
    ],
}

3. 使用方式 #

类视图（支持装饰器传参或自动提取） #

from drf_spectacular.utils import extend_schema
from rest_framework.views import APIView

@extend_schema(
    description="Get all responsible parties",
    responses={200: ResponsiblePartySerializer},
    permissions=['responsible_party.can_view_responsible_party']  # 自定义权限标识
)
class ResponsiblePartyListView(APIView):
    # 若装饰器未传permissions，会自动提取此处的权限类名称
    # permission_classes = [IsAuthenticated, CustomViewPermission]
    
    def get(self, request):
        # 接口逻辑...
        pass

函数视图 #

@extend_schema(
    description="Get a single responsible party",
    responses={200: ResponsiblePartySerializer},
    permissions=['responsible_party.can_view_single_responsible_party']
)
@api_view(['GET'])
@permission_classes([IsAuthenticated])
def responsible_party_detail(request, pk):
    # 接口逻辑...
    pass

效果说明 #

配置完成后，生成的Swagger UI中，每个接口的描述部分会自动追加所需权限字段，展示该接口需要的权限标识或权限类名称。如果需要更定制化的UI展示（比如单独的权限区块），可以基于drf-spectacular的x-扩展字段，将权限信息存入schema['x-permissions']，再通过自定义Swagger UI模板或插件渲染。

内容的提问来源于stack exchange，提问作者AlxVallejo