Django 2.0.1 + DRF 3.7.7自动生成API文档访问出现404错误求助

我之前在维护旧版本DRF项目时也碰到过一模一样的问题，结合你用的Django 2.0.1和DRF 3.7.7版本，给你几个靠谱的排查方向和解决方案：

1. 检查URL路由的顺序 #

Django的URL匹配是从上到下依次匹配的，如果你的docs/路由放在了通配符路由（比如path('<str:slug>/', ...)或者正则匹配^.*$的路由）后面，就会被前面的路由先“抢注”，导致docs路径根本到不了DRF的文档视图。

解决方法：把docs/的路由移到所有通配路由的最前面，比如：

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    # 先放docs路由
    path('docs/', include_docs_urls(title='My API')),
    # 其他业务路由放在后面
    path('api/v1/', include('myapp.urls')),
    path('<str:page_slug>/', views.page_detail),
]

2. 确认DRF文档的依赖包是否完整 #

DRF 3.7.x的自动文档功能依赖coreapi和coreschema这两个第三方包，虽然安装DRF时应该会自动安装，但有时候环境更新、虚拟环境重建可能会丢失这些依赖。

你可以重新安装对应版本的依赖：

pip install coreapi==2.3.3 coreschema==0.0.4

（这两个版本是和DRF 3.7.7兼容的稳定版本）

3. 检查权限配置是否拦截了文档请求 #

如果你的全局settings.py里修改了DEFAULT_PERMISSION_CLASSES，比如设置成了IsAuthenticated，那么未登录访问docs时，DRF可能会返回404（有些场景下权限不足会被伪装成资源不存在）。

可以临时给docs路由单独配置豁免权限，测试是否是这个问题：

from rest_framework.documentation import include_docs_urls
from rest_framework.permissions import AllowAny

urlpatterns = [
    path('docs/', include_docs_urls(title='My API', permission_classes=[AllowAny])),
    ...
]

如果能正常访问了，再根据需求调整全局权限或者给文档视图单独配置合适的权限。

4. 排查自定义中间件的干扰 #

如果项目里有自定义的中间件，可能会修改请求路径、拦截请求或者做了其他处理，导致docs路由无法正常匹配。

可以临时在settings.py的MIDDLEWARE列表里注释掉所有自定义中间件，重启服务后测试是否能访问docs。如果恢复正常，再逐个启用中间件排查问题所在。

5. 重启服务并清除缓存 #

有时候Django的开发服务器会缓存路由配置，或者浏览器缓存了旧的请求状态。试试以下操作：

• 彻底关闭Django开发服务器，重新启动
• 用浏览器的无痕模式访问http://localhost:8000/docs/
• 如果是生产环境，重启对应的应用服务（比如uWSGI、Gunicorn）

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