能，drf-spectacular提供更现代的OpenAPI 3.0生成能力，默认集成swagger-ui和redoc；需正确配置DEFAULT_SCHEMA_CLASS并挂载路由，自定义ViewSet方法须用@extend_schema显式标注，Serializer字段描述优先取help_text。
drf-spectacular 能不能直接替代 Swagger UI？
能，但不是“替代”，而是提供更现代、更符合 DRF 习惯的 OpenAPI 3.0 生成能力。它不自带 UI，但默认集成了 swagger-ui 和 redoc 两个前端渲染器，开箱即用。如果你之前用过 drf-yasg，会发现 drf-spectacular 对 ViewSet、Serializer、@extend_schema 的支持更自然，且对泛型视图和类视图方法级注解更友好。
安装和基础配置三步走
别跳过中间步骤，尤其是 DEFAULT_SCHEMA_CLASS 配置，漏掉会导致 get_schema_view() 返回空或 404。
- 运行
pip install drf-spectacular - 在
INSTALLED_APPS中添加'drf_spectacular' - 在
REST_FRAMEWORK配置里加："DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema"
然后在主 urls.py 中挂载路由：
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView
urlpatterns = [
path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
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'),
]
ViewSet 方法没出现在文档里？检查 @extend_schema 位置
drf-spectacular 默认只扫描 list、retrieve、create 等标准动作。自定义方法（比如 def publish(self, request)）必须显式标注，否则不会进 OpenAPI。
立即学习“Python免费学习笔记（深入）”；
- 在方法上加装饰器：
@extend_schema(description="发布文章，需 status=1")
- 如果返回自定义响应体，补上
responses参数：@extend_schema(responses={200: ArticleSerializer}) - 注意：不要在类级别用
@extend_schema_view覆盖整个 ViewSet 后，又在方法上重复加 —— 容易覆盖失效
常见错误现象：publish 接口在 Swagger UI 里完全不可见，或点击后报 405 Method Not Allowed，其实是 schema 没声明该 endpoint 导致前端没生成对应请求按钮。
Serializer 字段描述不显示？用 help_text 或 @extend_schema_field
drf-spectacular 优先读取字段的 help_text 作为 description。没设就留空，看着像“文档缺失”。
- 推荐写法：
title = serializers.CharField(help_text="文章标题，最大长度 100")
- 动态描述（比如根据环境变）用
@extend_schema_field：@extend_schema_field(serializers.CharField(help_text="仅测试环境可用"))
- 注意：字段级
label不会进 OpenAPI description，别指望它起作用
容易被忽略的是嵌套 Serializer 的字段 —— 如果外层用了 fields = '__all__'，但内层字段没写 help_text，那整块 description 就是空的，看起来像接口设计不规范。
