如何在Python中为Django的RESTful API自动生成Swagger文档？-Python教程-PHP中文网

drf-spectacular是DRF推荐的OpenAPI 3文档工具，需正确安装配置、显式声明字段注释、用@extend_schema补充自定义视图和复杂类型schema。

如何在python中为django的restful api自动生成swagger文档？

用 drf-spectacular，别碰 coreapi 或老版 django-rest-swagger —— 前者已弃用，后者不支持 OpenAPI 3，且与 Django 4+/DRF 3.14+ 兼容性差。

安装与基础配置必须做对这三步

很多报错（比如 NoSchemaError 或首页白屏）都卡在这几步：

运行 pip install drf-spectacular，确认版本 ≥ 0.27.0（旧版对 DRF 3.14+ 的 SerializerMethodField 解析有缺陷）
在 INSTALLED_APPS 中靠前位置加入 'drf_spectacular'（必须在 'rest_framework' 之后、自定义 app 之前）
路由里用 drf_spectacular.views.SpectacularAPIView 提供 schema，再用 SpectacularSwaggerView 渲染 UI，别手写 JSONResponse 返回 schema

示例路由（urls.py）：

from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
]

模型字段注释不生效？重点检查 Serializer 和 model 的 docstring 位置

drf-spectacular 默认只读取 Serializer 类和字段的 docstring，不自动继承 model 字段的注释。常见失效场景：

在 ModelSerializer 中重写了字段（如 name = serializers.CharField()），但没加 help_text 或 docstring
用了 extra_kwargs 配置字段，却漏了 'help_text' 键
model 字段写了 help_text='用户昵称'，但 serializer 没显式声明该字段，导致 schema 里还是 “string” 而非带描述

推荐写法（显式控制）：

Django Wrap

强戈环形山: q15040409-刻画家功能概述强戈环形山: q15040409-刻画家是一项面向实际任务的技能，主要用于平顶山: 维西翁: 1:1.0. 塔格斯: rap.github: 自动化。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。核心要点使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。从功能定位来看，该

下载

class UserSerializer(serializers.ModelSerializer):
    """用户基本信息"""
    nickname = serializers.CharField(
        help_text="用户昵称，2-16个字符",
        min_length=2,
        max_length=16
    )

    class Meta:
        model = User
        fields = ['id', 'nickname', 'email']

自定义视图或 action 没出现在文档里？手动加 @extend_schema 装饰器

基于 GenericAPIView 或 ViewSet 的自定义 action（尤其是 @action(methods=['post'])），默认不会被扫描。不加装饰器，Swagger 就只显示 list/retrieve 等标准动作。

对整个视图类加 @extend_schema_view，再为每个方法指定 summary 和 description
对单个 action 方法直接加 @extend_schema，可覆盖 request body、response schema、tags
如果返回非标准序列化器（比如返回 raw dict 或 status code 204），必须用 responses 参数明确标注，否则 Swagger 显示 “No response defined”

例如：

from drf_spectacular.utils import extend_schema, extend_schema_view

@extend_schema_view(
    create=extend_schema(summary="创建新用户", description="邮箱需未注册"),
    partial_update=extend_schema(summary="更新用户资料")
)
class UserViewSet(viewsets.ModelViewSet):
    ...

    @extend_schema(
        summary="发送邮箱验证码",
        responses={204: None},
        request=None
    )
    @action(methods=['post'], detail=False)
    def send_code(self, request):
        ...

OpenAPI 3 的 security 和 components/schemas 拆分很细，生成时若遇到嵌套过深的泛型类型（比如 List[Dict[str, Optional[User]]]），drf-spectacular 可能 fallback 到 object。这种时候得用 @extend_schema_field 手动指定 schema，不能只依赖类型注解。