[python]在drf中使用drf_spectacular

安装drf_spectacular

文档

pypi链接:https://pypi.org/project/drf-spectacular/

文档链接:https://drf-spectacular.readthedocs.io/en/latest/readme.html

安装步骤

1. 在环境中添加

pip install drf-spectacular

2. 在setting的INSTALLED_APPS中添加

INSTALLED_APPS = [# ALL YOUR APPS'drf_spectacular',
]

3. 在setting的REST_FRAMEWORK中添加

REST_FRAMEWORK = {# YOUR SETTINGS'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

4. 根据实机情况填写setting中的SPECTACULAR_SETTINGS,此内容为添加

SPECTACULAR_SETTINGS = {"TITLE": "Your API","DESCRIPTION": "API documentation","VERSION": "1.0.0",# "SERVE_INCLUDE_SCHEMA": True,"SWAGGER_UI_DIST": "/static/swagger-ui-dist/",  # 本地静态文件路径"SWAGGER_UI_FAVICON_HREF": "/static/swagger-ui-dist/favicon-32x32.png",  # 本地图标路径"REDOC_DIST": "redoc-dist",  # 如果需要 Redoc
}

5. 在url.py文件中添加

urlpatterns = [# YOUR PATTERNSpath('api/schema/', SpectacularAPIView.as_view(), name='schema'),# Optional UI:path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

解决UI在线无法使用的问题

下载https://github.com/swagger-api/swagger-ui中的release内容

并根据第四步中的SWAGGER_UI_DIST内容,把release的dist内容放到具体的路径上.

---

对接口进行说明

先展示一个实例

class UserViewSets(viewsets.ModelViewSet):queryset = user.objects.all()serializer_class = UserSerializersfilter_backends = [DjangoFilterBackend, OrderingFilter]ordering_fields = ["id"]filterset_fields = ["first_name"]# /user/search/?username=xxx# /user/search/?first_name=xxx@extend_schema(description="根据工号或者姓名查找用户",parameters=[OpenApiParameter(name="username",description="员工工号",required=False,type=OpenApiTypes.STR,location=OpenApiParameter.QUERY,default="358256",examples=[OpenApiExample(name="第一页", value=1, description="获取第一页数据"),OpenApiExample(name="第五页", value=5, description="获取第五页数据"),],),OpenApiParameter(name="first_name",description="员工姓名",required=False,type=OpenApiTypes.STR,location=OpenApiParameter.QUERY,default="谢斯",),],summary="用户详情接口",)@action(detail=False, methods=["get"], url_path="search")def search(self, request):username = request.query_params.get("username", None)first_name = request.query_params.get("first_name", None)queryset = self.get_queryset()if username:queryset = queryset.filter(username=username)if first_name:queryset = queryset.filter(first_name=first_name)serializer = self.get_serializer(queryset, many=True)return Response(serializer.data)

需要注意的点

在view.py文件中需要引入对应的内容

from drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiTypes, OpenApiExample

---

介绍SPECTACULAR_SETTINGS

配置项	类型	默认值	描述
基础配置
TITLE	str	“API”	API 文档的标题。
DESCRIPTION	str	“”	API 文档的描述（Markdown 支持）。
VERSION	str	“1.0.0”	API 的版本号。
SERVE_URLCONF	str	当前 urls.py	定义用于生成文档的 URL 配置。
SERVE_PATH	str	“/schema/”	OpenAPI Schema 的访问路径。
SERVE_INCLUDE_SCHEMA	bool	True	是否在 Swagger 页面中显示 Schema 链接。
接口过滤与路径匹配
配置项 类型 默认值 描述
SCHEMA_PATH_PREFIX	str	r"^api/"	匹配生成文档的 URL 路径（正则表达式）。
SCHEMA_PATH_PREFIX_TRIM	bool	False	是否移除路径前缀（如 /api/）以简化文档路径。
SCHEMA_COERCE_PATH_PK	bool	False	将路径中的 pk 强制转换为整数类型。
SCHEMA_URL_PREFIX	str	“”	为所有接口路径添加前缀（如 /v1/）。
认证与安全策略
AUTHENTICATION_CLASSES	list	项目默认的 REST_FRAMEWORK.AUTHENTICATION_CLASSES	指定需要包含在文档中的认证类（如 JWT, Token）。
SECURITY_DEFINITIONS	dict	{}	定义安全策略（如 OAuth2、JWT）。
SECURITY_REQUIREMENTS	list	[]	指定默认的安全要求（如 [“BearerAuth”]）。
组件与扩展
COMPONENT_SPLIT_REQUEST	bool	False	是否将请求和响应拆分为独立的组件（适用于复杂场景）。
ENUM_NAME_OVERRIDES	dict	{}	覆盖枚举字段的名称（如 ChoiceField）。
TAGS	list	从视图中自动提取	手动定义接口标签（分组）。
PREPROCESSING_HOOKS	list	[]	在生成 Schema 前自定义处理函数（如修改参数）。
POSTPROCESSING_HOOKS	list	[]	在生成 Schema 后自定义处理函数（如添加注释）。
UI 显示优化
SWAGGER_UI_SETTINGS	dict	{}	自定义 Swagger UI 的行为（如主题、操作排序）。
REDOC_SETTINGS	dict	{}	自定义 ReDoc 的行为（如样式、操作排序）。
SERVE_PUBLIC	bool	True	是否允许匿名用户访问文档页面。
高级配置
APPEND_COMPONENTS	dict	{}	手动添加 OpenAPI 组件（如自定义请求体格式）。
POSTPROCESSING_FILTER	callable	None	对生成的 Schema 进行过滤或修改。
EXTENSIONS	dict	{}	注册自定义扩展（如支持 GraphQL）。