djangodjango-rest-frameworkyamlswaggerapi-documentation

Why is everything grouped under "api" in Swagger UI with no division between task and subtask?

I'm working on documenting an API using Swagger UI. However, I've noticed that all endpoints are grouped under a single "api" section.

enter image description here

There are no separate divisions for different resources such as "task" and "subtask". This makes the API documentation harder to navigate and understand.

settings.py

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

urls.py

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/schema/', SpectacularAPIView.as_view(), name='api-schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='api-schema'), name='api-docs'),
    path('api/users/', include('user.urls')),
    path('api/tasks/', include('task.urls')),
    path('api/subtasks/', include('subtask.urls')),
]

task\urls.py

router = DefaultRouter()
router.register('', views.TaskViewSet)

app_name = 'task'

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

  • You can configure the SCHEMA_PATH_PREFIX in settings using the regex /api/:

    "SCHEMA_PATH_PREFIX": "/api/"

    For versioned URLs, such as /api/v1/something, you can use the following regex:

    "SCHEMA_PATH_PREFIX": "/api/v[0-9]/"

    Additionally, you can use the extend_schema decorator on your views to specify tags. For example:

    from drf_spectacular.utils import extend_schema

@extend_schema(methods=["get","post","..."], tags=["Tasks"])
class TaskViewSet(ViewSet):
  ....