Django 接口文档生成：Swagger 与 ReDoc 全面说明
目录
一、接口文档的意义
二、OpenAPI 与 Swagger 的概念
三、安装与配置
四、在 Django 中添加 Swagger 文档入口
五、编写示例接口，展示在 Swagger 中
定义序列化器
定义视图并添加 Swagger 注解
路由绑定
六、Swagger 与 ReDoc 的区别
1. Swagger UI
2. ReDoc
七、如不需要 ReDoc，可禁用
八、总结
本文介绍 Django 项目中使用 drf_yasg 自动生成接口文档的过程，包括 Swagger UI 与 ReDoc 的作用、区别和配置方式。文章适合对接口文档不熟悉的开发者阅读。
一、接口文档的意义
在前后端分离开发中，前端需要依赖后端提供的 API 才能与服务器交互。为了明确每个接口的作用、参数格式、返回值结构，需要一份可读、可维护的接口文档。
接口文档的核心目的包括：
- 明确接口地址、请求方式
- 展示参数格式、字段含义、是否必填
- 指明响应结构
- 帮助前后端对齐接口规范
- 提供调试入口，提高开发效率
为了解决传统手写文档易过时、维护困难的问题，可以使用自动化工具生成 API 文档。
二、OpenAPI 与 Swagger 的概念
OpenAPI 是一种接口描述规范，类似“文档格式标准”。
Swagger 是一套围绕 OpenAPI 的工具，用于：
- 生成可视化接口文档页面
- 提供调试界面
- 格式化展示参数和返回值结构
在 Django 中，常用的库是 drf_yasg。它的作用是：
- 自动读取 Django REST Framework 的视图、序列化器
- 自动生成 OpenAPI 格式文档
- 自动生成 Swagger UI 和 ReDoc 文档页面
三、安装与配置
安装依赖：
pip install drf_yasg djangorestframework在 Django settings 中启用：
INSTALLED_APPS = [..."rest_framework","drf_yasg",
]四、在 Django 中添加 Swagger 文档入口
在项目根目录的 urls.py 中添加如下配置：
from django.contrib import admin
from django.urls import path, re_path, include
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapischema_view = get_schema_view(openapi.Info(title="项目接口文档",default_version='v1',description="自动生成的 API 文档示例",),public=True,permission_classes=(permissions.AllowAny,),
)urlpatterns = [path('admin/', admin.site.urls),path('api/', include('api.urls')),# Swagger UI 文档re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='swagger-ui'),# ReDoc 文档re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='redoc'),
]启动 Django 服务器后，你将得到两种文档：
- Swagger UI
http://127.0.0.1:8000/swagger/ - ReDoc
http://127.0.0.1:8000/redoc/
五、编写示例接口，展示在 Swagger 中
定义序列化器
# api/serializers.py
from rest_framework import serializersclass LoginSerializer(serializers.Serializer):username = serializers.CharField()password = serializers.CharField()class UserSerializer(serializers.Serializer):id = serializers.IntegerField()username = serializers.CharField()email = serializers.EmailField()定义视图并添加 Swagger 注解
# api/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from drf_yasg.utils import swagger_auto_schema
from .serializers import LoginSerializer, UserSerializer
from drf_yasg import openapiclass UserLoginView(APIView):@swagger_auto_schema(operation_description="用户登录接口",request_body=LoginSerializer,responses={200: openapi.Response("成功",schema=openapi.Schema(type=openapi.TYPE_OBJECT,properties={'token': openapi.Schema(type=openapi.TYPE_STRING)}))},)def post(self, request):return Response({"token": "fake_token"})class UserInfoView(APIView):@swagger_auto_schema(operation_description="获取用户信息",responses={200: UserSerializer()})def get(self, request, uid):return Response({"id": uid,"username": "tom","email": "tom@example.com"})路由绑定
# api/urls.py
from django.urls import path
from .views import UserLoginView, UserInfoViewurlpatterns = [path('login/', UserLoginView.as_view()),path('user/<int:uid>/', UserInfoView.as_view()),
]访问 /swagger/ 即可看到自动生成的接口文档，包括参数、返回格式及在线调试功能。
六、Swagger 与 ReDoc 的区别
drf_yasg 自动生成两种文档页面，各有用途：
1. Swagger UI
地址：/swagger/
特点：
- 支持在线调试
- 页面偏技术化
- 功能较多
- 前后端开发人员适用
2. ReDoc
地址：/redoc/
特点：
- 页面结构更简洁
- 更适合作为正式接口说明文档
- 不提供在线调试按钮
- 更适合第三方阅读
两者均基于同一份 OpenAPI 文档，只是展示方式不同。
七、如不需要 ReDoc，可禁用
只需在 url 配置中删除：
re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0)),即可关闭 ReDoc 页面。
八、总结
- Django 使用 drf_yasg 可以自动生成接口文档
- Swagger UI 提供调试功能
- ReDoc 提供更简洁的接口阅读体验
- 两者都来自同一份 OpenAPI 文档
- 文档内容根据 serializer 和 view 自动同步更新
- 可根据项目需求选择保留或关闭某一种文档