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

一、前言

概述

在前后端分离开发中，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-yasgdrf-spectacular规范支持Swagger 2.0OpenAPI 3.0功能丰富度基础功能完善高级功能更丰富可定制性中等高学习曲线平缓稍陡推荐场景简单项目快速集成复杂项目、需要高级定制二、方案一：使用 drf-yasg（支持 Swagger 2.0）

工具介绍

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

• 动态生成 Swagger UI，支持多种主题
  
• 可自定义文档样式和内容
  
• 支持隐藏指定字段、添加额外参数等高级功能
  

安装步骤

安装

1. pip install -U drf-yasg

复制代码

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

1. INSTALLED_APPS = [
2.    # ...
3.    'django.contrib.staticfiles',  # 用于提供 Swagger UI 的静态文件
4.    'drf_yasg',
5.    # ...
6. ]

复制代码

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

1. from django.urls import re_path
2. from rest_framework import permissions
3. from drf_yasg.views import get_schema_view
4. from drf_yasg import openapi
6. # 配置 API 文档基本信息
7. schema_view = get_schema_view(
8.    openapi.Info(
9.       title="项目 API",
10.       default_version='v1',
11.       description="API 接口文档描述",
12.       terms_of_service="https://www.example.com/terms/",
13.       contact=openapi.Contact(email="contact@example.com"),
14.       license=openapi.License(name="MIT License"),
15.    ),
16.    public=True,
17.    permission_classes=(permissions.AllowAny,),  # 允许任何人访问文档
18. )
20. # 添加 URL 路由
21. urlpatterns = [
22.    # ...
23.    # 文档 JSON/YAML 下载
24.    path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
25.    # Swagger UI 页面
26.    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
27.    # ReDoc 页面
28.    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
29.    # ...
30. ]

复制代码

查看效果

启动 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 官方文档
安装步骤

安装

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

复制代码

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

1. INSTALLED_APPS = [
2.         # ...
3.     'drf_spectacular',
4.     'drf_spectacular_sidecar',  # 内置 UI 资源
5.     # ...
6. ]
8. # 配置 DRF
9. REST_FRAMEWORK = {
10.     # OpenAPI 文档
11.     'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
12. }
14. ### drf-spectacular OpenAPI 文档配置
15. SPECTACULAR_SETTINGS = {
16.     "SWAGGER_UI_DIST": "SIDECAR",  # 使用内置 UI
17.     "SWAGGER_UI_FAVICON_HREF": "SIDECAR",
18.     "TITLE": "MarsMgn API",
19.     "DESCRIPTION": "火星信息平台接口文档",
20.     "VERSION": "1.0.0",
21.     "SERVE_INCLUDE_SCHEMA": False,  # 不在文档中包含 schema 本身
22. }

复制代码

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

1. from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView
3. urlpatterns = [
4.     #...
5.     # API schema 生成端点
6.     path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
7.     # Swagger UI 界面
8.     path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
9.     # ReDoc 界面
10.     path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
11.     #...
12. ]

复制代码

查看效果

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

四、drf-spectacular 高级使用技巧

字段注释

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

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

复制代码

接口说明

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

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

复制代码

接口分组

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

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

复制代码

请求与响应参数定义

定义响应参数示例

1. from drf_spectacular.utils import extend_schema, OpenApiResponse
2. from drf_spectacular.types import OpenApiTypes
4. @extend_schema(
5.     responses={
6.         200: OpenApiResponse(
7.             description="操作成功",
8.             response={
9.                 "type": "object",
10.                 "properties": {
11.                     "code": {"type": "integer", "example": 0},
12.                     "data": {"type": "boolean", "example": True},
13.                     "msg": {"type": "string", "example": ""}
14.                 }
15.             }
16.         )
17.     }
18. )
19. def delete_post(self, request, *args, ​**kwargs):
20.     """删除岗位"""
21.     return Response({"code": 0, "data": True, "msg": ""}, status=200)

复制代码

您正在阅读的是《Django从入门到实战》专栏！关注不迷路~

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！