一、前言
概述
在前后端分离开发中，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 | drf-spectacular |
|---|---|---|
| 规范支持 | Swagger 2.0 | OpenAPI 3.0 |
| 功能丰富度 | 基础功能完善 | 高级功能更丰富 |
| 可定制性 | 中等 | 高 |
| 学习曲线 | 平缓 | 稍陡 |
| 推荐场景 | 简单项目快速集成 | 复杂项目、需要高级定制 |
二、方案一：使用 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_path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from 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<format>/', 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/
- 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-spectacular
pip install drf-spectacular[sidecar] # 安装内置 UI 资源（推荐）
配置 settings.py：点击查看完整代码
INSTALLED_APPS = [
# ...
'drf_spectacular',
'drf_spectacular_sidecar', # 内置 UI 资源
# ...
]
# 配置 DRF
REST_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, SpectacularSwaggerView
urlpatterns = [
#...
# 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
四、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, OpenApiResponse
from 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)
您正在阅读的是《Django从入门到实战》专栏！关注不迷路~
