目录
[二、OpenAPI 与 Swagger 的概念](#二、OpenAPI 与 Swagger 的概念)
[四、在 Django 中添加 Swagger 文档入口](#四、在 Django 中添加 Swagger 文档入口)
[五、编写示例接口，展示在 Swagger 中](#五、编写示例接口，展示在 Swagger 中)
[定义视图并添加 Swagger 注解](#定义视图并添加 Swagger 注解)
[六、Swagger 与 ReDoc 的区别](#六、Swagger 与 ReDoc 的区别)
[1. Swagger UI](#1. Swagger UI)
[2. ReDoc](#2. ReDoc)
[七、如不需要 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 openapi
schema_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 serializers
class 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 openapi
class 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, UserInfoView
urlpatterns = [
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 自动同步更新
- 可根据项目需求选择保留或关闭某一种文档