Django视图文档字符串中Swagger如何转义&等特殊字符？

我之前也踩过这个坑！在Django搭配Swagger（大概率是用drf-yasg做集成吧？这也是最常用的方案）开发时，在视图的文档字符串里写带&的URL查询参数示例，确实会因为特殊字符被错误解析导致展示异常。下面给你几个实用的解决办法：

1. 使用HTML实体转义& #

Swagger的文档渲染引擎会解析HTML内容，所以我们可以把URL里的&替换成对应的HTML实体&，这样就能避免被拆分解析。

示例视图代码：

from rest_framework.views import APIView

class UserListView(APIView):
    """
    获取系统用户列表
    ---
    查询参数示例：`/?first_name__icontains=saeed&age__gte=20`
    """
    def get(self, request):
        # 你的视图逻辑代码
        pass

这样Swagger页面会正确把&渲染成&符号，展示出完整的查询参数示例。

2. 将URL示例包裹在代码块中 #

如果想让示例更清晰，也可以把整个URL查询示例放在三重反引号包裹的代码块里，代码块内的特殊字符不会被Swagger的渲染引擎解析。

示例视图代码：

from rest_framework.views import APIView

class UserListView(APIView):
    """
    获取系统用户列表
    ---
    查询参数示例：
    ```
    /?first_name__icontains=saeed&age__gte=20
    ```
    """
    def get(self, request):
        # 你的视图逻辑代码
        pass

这种方式不仅能保留原始的&符号，还会让示例以代码样式展示，可读性更强。

3. 用序列化器定义查询参数（更规范的方案） #

其实更推荐的做法是不要在文档字符串里硬编码参数示例，而是利用drf-yasg的query_serializer来定义查询参数，这样Swagger会自动生成带示例的交互文档，从根源上避免特殊字符的问题。

示例代码：

from drf_yasg.utils import swagger_auto_schema
from rest_framework import serializers, views, response
from django.contrib.auth.models import User

class UserListQuerySerializer(serializers.Serializer):
    first_name__icontains = serializers.CharField(
        required=False, 
        help_text="模糊匹配用户姓名（不区分大小写）"
    )
    age__gte = serializers.IntegerField(
        required=False, 
        help_text="筛选年龄大于等于指定值的用户"
    )

class UserListView(views.APIView):
    @swagger_auto_schema(query_serializer=UserListQuerySerializer)
    def get(self, request):
        # 验证并解析查询参数
        query_serializer = UserListQuerySerializer(data=request.query_params)
        query_serializer.is_valid(raise_exception=True)
        
        # 执行查询
        users = User.objects.filter(**query_serializer.validated_data)
        
        # 返回响应（这里假设你有对应的用户序列化器）
        return response.Response(UserSerializer(users, many=True).data)

这种方式不仅解决了特殊字符的问题，还让API文档更规范，用户可以直接在Swagger页面输入参数进行接口测试，体验更好。

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