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-yasg(支持 Swagger 2.0)
工具介绍
drf-yasg 是基于 Django REST Framework (DRF) 的 API 文档生成工具,专注于 Swagger 2.0 规范,具有以下特点:
动态生成 Swagger UI,支持多种主题
可自定义文档样式和内容
支持隐藏指定字段、添加额外参数等高级功能
安装步骤
安装
配置 settings.py:在 INSTALLED_APPS
中添加相关应用
配置 urls.py:添加 Swagger 相关路由
查看效果
启动 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 官方文档
安装步骤
安装
配置 settings.py:点击查看完整代码
配置 urls.py:点击查看完整代码
查看效果
启动 Django 项目后,通过以下地址访问 Swagger UI 界面:http://127.0.0.1:8000/api/schema/swagger-ui

四、drf-spectacular 高级使用技巧
字段注释
文档描述优先从序列化器 / 模型的 help_text
提取:
接口说明
使用 @extend_schema
装饰器自定义接口描述:
接口分组
通过 tags
参数对接口进行分组:
请求与响应参数定义
定义响应参数示例
文章转载自:小王子1024
评论