写点什么

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

  • 2025-07-25
    福建
  • 本文字数:2781 字

    阅读完需:约 9 分钟

一、前言


概述

在前后端分离开发中,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<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-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, 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, 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

原文链接:https://www.cnblogs.com/xwz1024/p/18997086

体验地址:http://www.jnpfsoft.com/?from=001YH

用户头像

还未添加个人签名 2023-06-19 加入

还未添加个人简介

评论

发布
暂无评论
Django集成Swagger全指南:两种实现方案详解_django_不在线第一只蜗牛_InfoQ写作社区