Django如何将ASGI WebSocket路径添加到drf-yasg生成的Swagger文档

核心原因 #

drf-yasg默认仅扫描Django REST Framework的HTTP视图类路由，Channels的Consumer不属于DRF视图范畴，就算写入HTTP路由列表也会被drf-yasg过滤，且OpenAPI 2.0本身没有专门的WebSocket协议定义，因此默认不会生成对应WS端点的文档。

解决方法 #

方法1：添加文档专用假视图（推荐） #

该方案完全兼容现有generate_swagger命令流程，无需额外脚本适配：

1. 定义两个仅用于生成文档的空DRF视图，配置好路径参数、描述信息：

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

class WSSessionsSummaryDocView(APIView):
    @swagger_auto_schema(
        operation_id="websocket_sessions_summary",
        operation_description="*WebSocket端点，需使用ws/wss协议连接*，连接成功后将实时推送会话汇总数据",
        manual_parameters=[
            openapi.Parameter(
                name="uuid",
                in_=openapi.IN_PATH,
                description="资源唯一标识",
                type=openapi.TYPE_STRING,
                required=True
            ),
        ],
        responses={
            101: openapi.Response("WebSocket连接成功，协议切换完成")
        }
    )
    def get(self, request, uuid):
        # 该视图不会处理实际业务请求，仅用于生成文档
        return Response(status=status.HTTP_501_NOT_IMPLEMENTED)

class WSSessionsDocView(APIView):
    @swagger_auto_schema(
        operation_id="websocket_sessions",
        operation_description="*WebSocket端点，需使用ws/wss协议连接*，用于实时会话交互",
        manual_parameters=[
            openapi.Parameter(
                name="uuid",
                in_=openapi.IN_PATH,
                description="资源唯一标识",
                type=openapi.TYPE_STRING,
                required=True
            ),
        ],
        responses={
            101: openapi.Response("WebSocket连接成功，协议切换完成")
        }
    )
    def get(self, request, uuid):
        return Response(status=status.HTTP_501_NOT_IMPLEMENTED)

2. 将两个假视图添加到你的HTTP路由urlpatterns中：

urlpatterns = [
    path(r'v1/toto/<str:uuid>', MyView.as_view()),
    # 其他原有HTTP路由
    # 文档专用WS路由，路径和实际WS端点完全一致
    path(r'v1/ws/yo/<str:uuid>/sessions-sumpup', WSSessionsSummaryDocView.as_view()),
    path(r'v1/ws/yo/<str:uuid>/sessions', WSSessionsDocView.as_view()),
]

注意：实际的WS路由仍保留在Channels的routing.py配置中即可，假视图不会处理实际请求，也不会影响WebSocket的正常连接逻辑，ASGI的ProtocolTypeRouter会自动将ws/wss协议的请求分发到Channels路由处理。

方法2：生成文档后手动/脚本注入路径 #

如果不想修改现有路由配置，可在执行python3 manage.py generate_swagger swagger.yaml后，手动向生成的yaml文件中添加WS端点定义，示例格式如下：

paths:
  # 原有其他HTTP路径保留
  /v1/ws/yo/{uuid}/sessions-sumpup:
    get:
      summary: 会话汇总WebSocket端点
      description: 使用ws/wss协议连接，实时推送会话汇总数据
      parameters:
        - name: uuid
          in: path
          required: true
          type: string
      responses:
        101:
          description: WebSocket连接成功
  /v1/ws/yo/{uuid}/sessions:
    get:
      summary: 会话交互WebSocket端点
      description: 使用ws/wss协议连接，用于实时会话交互
      parameters:
        - name: uuid
          in: path
          required: true
          type: string
      responses:
        101:
          description: WebSocket连接成功

Google Endpoint适配说明 #

生成的OpenAPI文档路径和参数和实际WS端点完全匹配即可，Google Endpoint支持识别该类定义为WebSocket端点，只要后端路由配置正确即可正常转发请求。

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