Swagger UI所有接口归为“api”组，无任务/子任务分组问题排查

当前使用drf-spectacular生成Swagger文档时，所有接口都被归类到单一的“api”分组下，无法按task、subtask等资源独立划分，导致文档导航和理解难度提升。以下是几种可行的解决方法：

方法1：给ViewSet手动指定分组标签 #

直接在每个资源对应的ViewSet类上，使用drf_spectacular.utils.extend_schema装饰器指定tags参数，明确接口所属分组。

以TaskViewSet为例：

from rest_framework import viewsets
from drf_spectacular.utils import extend_schema
from .models import Task
from .serializers import TaskSerializer

@extend_schema(tags=['Tasks'])
class TaskViewSet(viewsets.ModelViewSet):
    queryset = Task.objects.all()
    serializer_class = TaskSerializer

同理，给SubtaskViewSet添加@extend_schema(tags=['Subtasks'])，UserViewSet添加@extend_schema(tags=['Users'])。重启服务后，Swagger UI会自动将对应接口分到指定分组。

方法2：利用Router basename自动生成分组 #

如果不想逐个修改ViewSet，可以通过Router注册时的basename参数，结合drf-spectacular的配置自动生成分组标签。

1. 修改各app的urls.py，注册Router时添加basename：

# task/urls.py
router = DefaultRouter()
router.register('', views.TaskViewSet, basename='task')  # 新增basename参数

app_name = 'task'
urlpatterns = [
    path('', include(router.urls)),
]

2. 在settings.py中添加SPECTACULAR_SETTINGS配置，开启自动分组：

SPECTACULAR_SETTINGS = {
    'AUTO_TAG': True,
    'TAG_NAME_FUNCTION': lambda path, path_regex, method, view: view.basename.capitalize() if hasattr(view, 'basename') else 'api',
}

该配置会自动将ViewSet的basename转为首字母大写的分组标签（如task转为Task），实现接口按资源分组。

方法3：根据URL路径自动分组 #

如果希望直接根据URL中的资源路径（如/api/tasks/）生成分组标签，可以通过配置TAG_NAME_FUNCTION实现：

在settings.py中添加：

SPECTACULAR_SETTINGS = {
    'TAG_NAME_FUNCTION': lambda path, path_regex, method, view: path.split('/')[2].capitalize() if len(path.split('/'))>2 else 'api',
}

这个函数会从URL路径中提取资源名称（如/api/tasks/提取tasks），转为首字母大写的分组标签，无需修改ViewSet或Router配置。

完成上述任意一种配置后，重启服务并访问/api/docs/，即可看到接口按Tasks、Subtasks、Users等资源独立分组展示，提升文档的导航性。

内容的提问来源于stack exchange，提问作者coder