Swagger中Django反向工程的使用方法及相关文档问询

首先明确：我们说的在Swagger中应用Django反向工程，实际是指从已有的Django业务代码（模型、DRF视图、序列化器等）自动生成符合OpenAPI/Swagger规范的接口文档，无需手动编写Swagger配置项。

前置依赖安装 #

优先使用适配性更强的drf-spectacular，支持Django 3.2+、DRF 3.10+全版本，执行安装命令：

pip install drf-spectacular

如果是维护旧版Django项目（Django <3.2），可以选用drf-yasg。

核心配置步骤 #

• 第一步：注册应用
  在项目settings.py的INSTALLED_APPS中添加配置：

INSTALLED_APPS = [
    # 原有其他应用
    'drf_spectacular',
]

• 第二步：添加DRF默认 schema 配置
  同样在settings.py中新增如下配置：

REST_FRAMEWORK = {
    # 原有其他DRF配置
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

# Swagger基础信息自定义
SPECTACULAR_SETTINGS = {
    'TITLE': '你的项目API文档',
    'DESCRIPTION': '从Django项目自动生成的Swagger接口文档',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

• 第三步：配置访问路由
  在项目根urls.py中添加Swagger页面和schema文件的访问路由：

from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    # 原有其他路由
    path('schema/', SpectacularAPIView.as_view(), name='schema'),
    # Swagger UI访问地址
    path('swagger/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
]

• 第四步：启动项目验证
  执行python manage.py runserver启动服务后，访问http://127.0.0.1:8000/swagger/即可看到自动生成的完整Swagger文档，所有现有Django接口的请求参数、返回结构、请求方式都会自动从代码解析生成，代码修改后文档会自动同步，完成反向工程效果。

进阶操作 #

• 要导出完整的Swagger规范文件，直接执行命令即可离线生成：

python manage.py spectacular --file swagger_schema.yml

• 代码中的注释、序列化器help_text参数、视图的docstring都会自动同步到Swagger文档的对应说明位置，无需单独配置Swagger字段。

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