django对接drf-spectacular替代swagger

django对接drf-spectacular替代swagger

1.1、安装drf-spectacular

pip install drf-spectacular
pip install django-restframework

1.2 配置 Django 设置

# settings.py

INSTALLED_APPS = [
# ...
'drf_spectacular', # 添加此项
'rest_framework', # 确保 DRF 已添加
# ...
]

REST_FRAMEWORK = {
# 你其他的 DRF 配置...
# ...

# !!! 最关键的一步：指定默认的 schema 类为 DRF-Spectacular 的 AutoSchema !!!
'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

# (可选) 为 DRF-Spectacular 添加一些自定义配置
SPECTACULAR_SETTINGS = {
'TITLE': 'My Awesome API',
'DESCRIPTION': '这是一个为我的项目提供的详细 API 文档',
'VERSION': '1.0.0',
'SERVE_INCLUDE_SCHEMA': False, # 是否在文档中包含原始的 Schema 数据端点（通常设为False）
# 其他设置...
}

1.3 配置 URL 路由 (urls.py)

在你的主 urls.py 文件中，添加用于访问 Schema 文件和交互式文档的端点。

# myproject/urls.py

from django.contrib import admin
from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView

urlpatterns = [
path('admin/', admin.site.urls),
path('api/', include('myapp.urls')), # 你的应用 API 路由

# DRF-Spectacular 路由：
# 1. 下载 Schema 文件 (YAML格式)
path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
# 2. Swagger UI 文档界面 (美观、可交互)
path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
# 3. ReDoc 文档界面 (简洁、可读性强)
path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

1.4配置视图

from django.shortcuts import render, HttpResponse
from drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiExample, OpenApiTypes
from rest_framework.decorators import api_view


@extend_schema(
# 指定该视图处理的 HTTP 方法，通常与 @api_view 保持一致
methods=["GET"],

# 还可以添加更多 OpenAPI 规范，例如摘要、描述、参数等
summary="登录模块",
description="""
这个API端点用于创建一个新的项目。
需要用户认证。
""",
parameters=[
OpenApiParameter(
name='category',
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description='产品分类',
required=False,
# enum=['electronics', 'books', 'clothing'] # 限定可选值
),
],
responses={
200: "成功", # 成功响应，返回单个对象
201: "失败", # 创建成功响应
400: None, # 错误响应，但没有固定的数据结构体（可能直接返回错误字符串）
403: None, # 权限错误
404: None, # 未找到
}
)
@api_view(['GET', 'POST'])
# @permission_classes([IsAuthenticated])
def login(request):
return HttpResponse("登录页面")

常见 OpenApiTypes 常量及其含义

以下是常用的类型常量列表，它们都位于 drf_spectacular.types 模块中。

OpenApiTypes 常量	对应的 OpenAPI 类型	说明	示例
基本类型
BOOL	boolean	布尔值	true, false
INT	integer	整数	1, -5, 0
INT32	integer (format: int32)	32位整数
INT64	integer (format: int64)	64位整数
FLOAT	number (format: float)	浮点数	3.14, -2.5
DOUBLE	number (format: double)	双精度浮点数
STR	string	字符串	"hello"
BYTE	string (format: byte)	Base64 编码的字节
BINARY	string (format: binary)	二进制数据（文件）
格式化的字符串
DATE	string (format: date)	ISO 8601 日期格式	"2023-10-27"
DATETIME	string (format: date-time)	ISO 8601 日期时间格式	"2023-10-27T10:30:00Z"
UUID	string (format: uuid)	UUID 字符串	"550e8400-e29b-41d4-a716-446655440000"
EMAIL	string (format: email)	电子邮件地址	"user@example.com"
IP	string (format: ip)	IP 地址（v4 或 v6）	"192.168.1.1"
URI	string (format: uri)	统一资源标识符	"https://example.com"
复合类型
OBJECT	object	JSON 对象	{"key": "value"}
ANY	{} (无类型限制)	任意类型	123, "string", {}