[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 PATTERNS
    path('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 = UserSerializers
    filter_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）。