本文介紹了在 Django 項目中集成 Swagger 的兩種主流方案 —— drf-yasg 和 drf-spectacular，涵蓋安裝配置、效果展示及高級用法，助力開發者高效構建交互式 API 文檔系統，提升前后端協作效率。

一、前言

概述

在前后端分離開發中，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 提?。?/p>

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從入門到實戰》專欄！關注不迷路~