网站导航
> 技术文档 > Django集成Swagger全指南：两种实现方案详解

Django集成Swagger全指南：两种实现方案详解

网友: 技术文档 2025-07-26 19:54:36

一、前言

概述

在前后端分离开发中，API 文档的重要性不言而喻。Swagger（现更名为 OpenAPI）作为主流的 API 文档生成工具，能自动生成交互式文档，极大提升开发效率。本文将介绍两种在 Django 项目中集成 Swagger 的实用方案，帮助开发者快速搭建完善的 API 文档系统。

什么是 Swagger/OpenAPI？

Swagger 是一套用于描述、生成、消费和可视化 RESTful API 的规范和工具集，目前已演进为 OpenAPI 规范：

  • Swagger 2.0：支持 WebSockets、OAuth2、文件上传等功能，提升了 API 描述的精确度

  • OpenAPI 3.0：下一代规范，提供更严格的模式验证、更多数据类型支持和更好的扩展性

通过集成 Swagger，开发者可以获得：

  • 自动生成的交互式 API 文档

  • 在线接口调试功能

  • 标准化的 API 描述格式（JSON/YAML）

  • 便于前后端协作和 API 版本管理

两种方案对比

二、方案一：使用 drf-yasg（支持 Swagger 2.0）

工具介绍

drf-yasg 是基于 Django REST Framework (DRF) 的 API 文档生成工具，专注于 Swagger 2.0 规范，具有以下特点：

  • 动态生成 Swagger UI，支持多种主题

  • 可自定义文档样式和内容

  • 支持隐藏指定字段、添加额外参数等高级功能

安装步骤

安装

pip install -U drf-yasg

配置settings.py：在 INSTALLED_APPS 中添加相关应用

INSTALLED_APPS = [ # ... \'django.contrib.staticfiles\', # 用于提供 Swagger UI 的静态文件 \'drf_yasg\', # ...]

配置urls.py：添加 Swagger 相关路由

from django.urls import re_pathfrom rest_framework import permissionsfrom drf_yasg.views import get_schema_viewfrom drf_yasg import openapi# 配置 API 文档基本信息schema_view = get_schema_view( openapi.Info( title=\"项目 API\", default_version=\'v1\', description=\"API 接口文档描述\", terms_of_service=\"https://www.example.com/terms/\", contact=openapi.Contact(email=\"contact@example.com\"), license=openapi.License(name=\"MIT License\"), ), public=True, permission_classes=(permissions.AllowAny,), # 允许任何人访问文档)# 添加 URL 路由urlpatterns = [ # ... # 文档 JSON/YAML 下载 path(\'swagger/\', schema_view.without_ui(cache_timeout=0), name=\'schema-json\'), # Swagger UI 页面 path(\'swagger/\', schema_view.with_ui(\'swagger\', cache_timeout=0), name=\'schema-swagger-ui\'), # ReDoc 页面 path(\'redoc/\', schema_view.with_ui(\'redoc\', cache_timeout=0), name=\'schema-redoc\'), # ...]

查看效果

启动 Django 项目后，通过以下地址访问文档：

  • Swagger UI 界面：http://localhost:8000/swagger/

image-20241009183315554

  • ReDoc 界面：http://localhost:8000/redoc/

  • 下载 JSON 格式文档：http://localhost:8000/swagger.json

  • 下载 YAML 格式文档：http://localhost:8000/swagger.yaml

三、方案二：使用 drf-spectacular（支持 OpenAPI 3.0）

工具介绍

drf-spectacular 是新一代 API 文档生成工具，支持 OpenAPI 3.0 规范，具有以下优势：

  • 更强的可扩展性和可定制性

  • 支持客户端代码生成

  • 兼容多种 DRF 插件

  • 提供更丰富的文档装饰器

参考资料： drf-spectacular 官方文档

安装步骤

安装

pip install drf-spectacularpip install drf-spectacular[sidecar] # 安装内置 UI 资源（推荐）

配置 settings.py：点击查看完整代码

INSTALLED_APPS = [# ... \'drf_spectacular\', \'drf_spectacular_sidecar\', # 内置 UI 资源 # ...]# 配置 DRFREST_FRAMEWORK = { # OpenAPI 文档 \'DEFAULT_SCHEMA_CLASS\': \'drf_spectacular.openapi.AutoSchema\',}### drf-spectacular OpenAPI 文档配置SPECTACULAR_SETTINGS = { \"SWAGGER_UI_DIST\": \"SIDECAR\", # 使用内置 UI \"SWAGGER_UI_FAVICON_HREF\": \"SIDECAR\", \"TITLE\": \"MarsMgn API\", \"DESCRIPTION\": \"火星信息平台接口文档\", \"VERSION\": \"1.0.0\", \"SERVE_INCLUDE_SCHEMA\": False, # 不在文档中包含 schema 本身}

配置 urls.py：点击查看完整代码

from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerViewurlpatterns = [ #... # API schema 生成端点 path(\'api/schema/\', SpectacularAPIView.as_view(), name=\'schema\'), # Swagger UI 界面 path(\'api/schema/swagger-ui/\', SpectacularSwaggerView.as_view(url_name=\'schema\'), name=\'swagger-ui\'), # ReDoc 界面 path(\'api/schema/redoc/\', SpectacularRedocView.as_view(url_name=\'schema\'), name=\'redoc\'), #...]

查看效果

启动 Django 项目后，通过以下地址访问 Swagger UI 界面：http://127.0.0.1:8000/api/schema/swagger-ui

image-20250722082135270

四、drf-spectacular 高级使用技巧

字段注释

文档描述优先从序列化器 / 模型的 help_text 提取：

class SystemPost(models.Model): id = models.BigAutoField(primary_key=True, help_text=\"岗位ID\") code = models.CharField( max_length=64, help_text=\"岗位编码\", # 会显示在文档中 )

接口说明

使用 @extend_schema 装饰器自定义接口描述：

from drf_spectacular.utils import extend_schema@extend_schema(summary=\"创建岗位\", description=\"自定义接口详细说明\")@action(methods=[\"post\"], detail=False, url_path=\"create\")def create_post(self, request, *args, **kwargs): return self.custom_create(request, *args, **kwargs)

接口分组

通过 tags 参数对接口进行分组：

@extend_schema(tags=[\"管理后台-system-岗位\"])class PostViewSet(CustomViewSet): queryset = SystemPost.objects.all() filterset_class = SystemPostFilter

请求与响应参数定义

定义响应参数示例

from drf_spectacular.utils import extend_schema, OpenApiResponsefrom drf_spectacular.types import OpenApiTypes@extend_schema( responses={ 200: OpenApiResponse( description=\"操作成功\", response={ \"type\": \"object\", \"properties\": {  \"code\": {\"type\": \"integer\", \"example\": 0},  \"data\": {\"type\": \"boolean\", \"example\": True},  \"msg\": {\"type\": \"string\", \"example\": \"\"} } } ) })def delete_post(self, request, *args, ​**kwargs): \"\"\"删除岗位\"\"\" return Response({\"code\": 0, \"data\": True, \"msg\": \"\"}, status=200)

文章转载自：小王子1024

原文链接：Django集成Swagger全指南：两种实现方案详解 - 小王子1024 - 博客园

体验地址：JNPF快速开发平台

网络标签：

相关问题