Django FormView接口无法在Swagger页面展示的解决方案咨询

核心思路 #

drf_yasg默认仅识别DRF的APIView子类，普通Django视图需手动添加OpenAPI Schema定义，并确保被Swagger的Schema Generator扫描到。

方法1：为视图添加@swagger_auto_schema装饰器 #

自定义FormView的处理 #

对于自己编写的FormView，直接为其dispatch方法添加装饰器，手动定义请求体、响应和接口描述：

from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi
from django.views.generic.edit import FormView
from .forms import RegisterForm

class RegisterView(FormView):
    form_class = RegisterForm
    template_name = 'register.html'
    success_url = '/login/'

    @swagger_auto_schema(
        method='post',
        request_body=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            properties={
                'username': openapi.Schema(type=openapi.TYPE_STRING, description='用户名'),
                'password1': openapi.Schema(type=openapi.TYPE_STRING, description='密码'),
                'password2': openapi.Schema(type=openapi.TYPE_STRING, description='确认密码'),
                # 补充表单其他字段
            },
            required=['username', 'password1', 'password2']
        ),
        responses={
            200: openapi.Response(
                description='注册成功',
                schema=openapi.Schema(
                    type=openapi.TYPE_OBJECT,
                    properties={
                        'status': openapi.Schema(type=openapi.TYPE_STRING, example='success'),
                        'message': openapi.Schema(type=openapi.TYPE_STRING, example='注册成功')
                    }
                )
            ),
            400: openapi.Response(description='表单验证失败，字段不符合要求')
        },
        operation_description='用户注册接口，提交表单完成注册'
    )
    # 可选：添加GET方法的schema（用于显示表单页面的接口描述）
    @swagger_auto_schema(
        method='get',
        responses={200: openapi.Response(description='返回注册表单页面')}
    )
    def dispatch(self, request, *args, **kwargs):
        return super().dispatch(request, *args, **kwargs)

第三方视图（如django.contrib.auth的LoginView）的处理 #

对于无法直接修改的内置视图，在URL配置中用装饰器包装视图实例：

from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi
from django.contrib.auth.views import LoginView
from django.urls import path

# 为LoginView包装swagger schema
login_view_with_swagger = swagger_auto_schema(
    method='post',
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={
            'username': openapi.Schema(type=openapi.TYPE_STRING, description='用户名'),
            'password': openapi.Schema(type=openapi.TYPE_STRING, description='密码'),
        },
        required=['username', 'password']
    ),
    responses={
        200: openapi.Response(description='登录成功，跳转至指定页面'),
        400: openapi.Response(description='用户名或密码错误')
    },
    operation_description='用户登录接口，验证身份后跳转'
)(LoginView.as_view(template_name='login.html'))

# 配置URL
urlpatterns = [
    # ... 其他URL
    path('login/', login_view_with_swagger, name='login'),
    path('register/', RegisterView.as_view(), name='register'),
]

方法2：自定义Schema Generator，强制扫描Django视图 #

如果需要批量处理多个Django视图，可以自定义Schema Generator，将非DRF视图纳入扫描范围：

from drf_yasg.generators import OpenAPISchemaGenerator
from django.urls import resolve

class DjangoCompatibleSchemaGenerator(OpenAPISchemaGenerator):
    def get_endpoints(self, request):
        # 先获取DRF视图的endpoints
        endpoints = super().get_endpoints(request)
        
        # 手动添加需要展示的Django视图
        # 示例：添加register和login视图
        for path_name, view_info in [
            ('/register/', ('post', 'register')),
            ('/login/', ('post', 'login'))
        ]:
            view_func = resolve(path_name).func
            # 处理类视图
            if hasattr(view_func, 'view_class'):
                view_class = view_func.view_class
                method, endpoint_name = view_info
                endpoints[endpoint_name] = (view_class, method, path_name)
        
        return endpoints

然后在生成Swagger视图时指定这个Generator：

from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="项目API文档",
        default_version='v1',
        description="包含Django视图和DRF接口的完整文档",
    ),
    public=True,
    generator_class=DjangoCompatibleSchemaGenerator,
    # 可选：指定要扫描的URL patterns，缩小范围
    # patterns=urlpatterns,
)

# 添加Swagger页面的URL
urlpatterns += [
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]

关键注意事项 #

1. 必须指定HTTP方法：@swagger_auto_schema的method参数要明确对应视图支持的方法（如GET/POST），否则Swagger无法正确识别。
2. Schema定义要匹配实际请求：request_body的字段需与表单字段完全一致，required列表要包含必填项。
3. URL必须被Swagger扫描：确保目标视图的URL被包含在get_schema_view的patterns参数中，或者被自定义Generator捕获。

内容的提问来源于stack exchange，提问作者Mr. Yao