django_debug_toolbar与drf_spectacular共存时API调用报Not Found问题

一、问题根源 #

• 调试工具栏中间件误拦截API请求：django_debug_toolbar的中间件会处理所有请求，当Swagger页面发起API调用时，中间件可能错误介入这些请求，因请求路径不符合工具栏的内部规则，返回404错误。
• 工具栏显示回调未排除Swagger路径：默认的SHOW_TOOLBAR_CALLBACK没有过滤drf_spectacular相关的页面和API路径，导致工具栏在这些请求中异常加载，干扰正常请求流程。
• 静态资源路径冲突：drf_spectacular的Swagger UI静态资源与django_debug_toolbar的静态资源路径存在重叠，引发请求寻址错误。

二、解决办法 #

1. 自定义工具栏显示回调，排除Swagger相关路径 #

在项目settings.py中添加自定义回调函数，让调试工具栏不在Swagger相关路径生效：

def show_toolbar(request):
    # 排除Swagger、Redoc及API Schema路径
    excluded_paths = ['/swagger/', '/redoc/', '/api/schema/']
    if any(request.path.startswith(path) for path in excluded_paths):
        return False
    # 保留调试模式及内部IP的判断逻辑
    return bool(settings.DEBUG and request.META.get('REMOTE_ADDR') in settings.INTERNAL_IPS)

DEBUG_TOOLBAR_CONFIG = {
    'SHOW_TOOLBAR_CALLBACK': '你的项目名.settings.show_toolbar',
}

2. 调整中间件顺序 #

将DebugToolbarMiddleware放在所有DRF相关中间件之后，避免提前拦截API请求：

MIDDLEWARE = [
    # 其他基础中间件...
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    # DRF相关中间件
    'rest_framework.middleware.AuthenticationMiddleware',
    # 调试工具栏中间件放在最后
    'debug_toolbar.middleware.DebugToolbarMiddleware',
]

3. 确保静态资源配置正确 #

• 运行命令收集静态资源：

python manage.py collectstatic

• 检查STATIC_URL和STATIC_ROOT配置，确保两个工具的静态资源都能正常访问。

4. 验证drf_spectacular路由配置 #

确认路由无冲突，示例配置如下：

# urls.py
from django.urls import path
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView

urlpatterns = [
    # 其他业务路由...
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('swagger/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

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