如何使用swagger_auto_schema将方法标记为已弃用？

drf-yasg 自带的swagger_auto_schema装饰器原生支持deprecated标记，和swagger-auto-schema的规则完全兼容，按以下场景配置即可：

1. 函数视图（FBV）配置 #

直接在接口的swagger_auto_schema装饰器中添加deprecated=True参数：

from drf_yasg.utils import swagger_auto_schema
from rest_framework.decorators import api_view

@swagger_auto_schema(
    method="get",
    operation_summary="旧版用户信息查询接口",
    deprecated=True  # 核心配置，标记接口为已弃用
)
@api_view(["GET"])
def old_user_info(request):
    # 接口逻辑实现
    pass

2. 类视图（CBV）配置 #

分为单方法标记和全类标记两种场景：

2.1 类中单个方法标记为弃用 #

使用method_decorator包装swagger_auto_schema装饰器标记对应方法即可：

from django.utils.decorators import method_decorator
from drf_yasg.utils import swagger_auto_schema
from rest_framework.viewsets import ModelViewSet

class GoodsViewSet(ModelViewSet):
    # 其他正常接口方法
    
    @method_decorator(swagger_auto_schema(deprecated=True))
    def list(self, request, *args, **kwargs):
        # 已弃用的列表查询逻辑
        return super().list(request, *args, **kwargs)

2.2 类下所有指定请求方法标记为弃用 #

直接在类上添加swagger_auto_schema装饰器，指定要标记的方法列表即可：

from drf_yasg.utils import swagger_auto_schema
from rest_framework.views import APIView

@swagger_auto_schema(
    deprecated=True,
    methods=["get", "post"] # 配置需要标记为弃用的该类下的请求方法
)
class OldOrderView(APIView):
    def get(self, request):
        # 已弃用的查询逻辑
        pass
    
    def post(self, request):
        # 已弃用的提交逻辑
        pass

效果说明 #

• 生成的Swagger文档中，被标记的端点会显示灰色删除线样式的路径
• 接口详情页会明确标注 Deprecated 标识，提示调用方该接口已不建议使用
• 该标记和swagger-auto-schema的自定义字段规则互不冲突，可以正常共存

注意：请确保你安装的drf-yasg版本不低于1.20.0，旧版本可能存在deprecated参数不生效的问题，可执行pip show drf-yasg命令查看当前版本。

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