在Django中集成Swagger时出现coreapi.Document缺失错误，如何解决？

问题场景 #

尝试为Django 4.1配置Swagger UI，添加renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer]后访问首页出现错误；移除该参数则无错误，但无法显示预期的Swagger界面。

代码示例 #

urls.py #

from django.urls import path
from djangofun import views
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer

schema_view = get_schema_view(title='API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

urlpatterns = [
    path('', schema_view),
    path('hello/', views.hello)
]

views.py #

from django.http import HttpResponse
from django.views.decorators.http import require_http_methods

@require_http_methods(["GET"])
def hello(request):
    return HttpResponse("Hello world")

错误信息 #

访问localhost首页时触发服务器错误，错误回溯如下：

Environment:

Request Method: GET
Request URL: http://localhost/

Django Version: 4.1
Python Version: 3.9.13
Installed Applications:
['django.contrib.admin',
 'django.contrib.auth',
 'django.contrib.contenttypes',
 'django.contrib.sessions',
 'django.contrib.messages',
 'django.contrib.staticfiles',
 'rest_framework',
 'rest_framework_swagger']
Installed Middleware:
['django.middleware.security.SecurityMiddleware',
 'django.contrib.sessions.middleware.SessionMiddleware',
 'django.middleware.common.CommonMiddleware',
 'django.middleware.csrf.CsrfViewMiddleware',
 'django.contrib.auth.middleware.AuthenticationMiddleware',
 'django.contrib.messages.middleware.MessageMiddleware',
 'django.middleware.clickjacking.XFrameOptionsMiddleware']

Traceback (most recent call last):
  File "/usr/local/lib/python3.9/site-packages/django/core/handlers/exception.py", line 55, in inner
    response = get_response(request)
  File "/usr/local/lib/python3.9/site-packages/django/core/handlers/base.py", line 220, in _get_response
    response = response.render()
  File "/usr/local/lib/python3.9/site-packages/django/template/response.py", line 114, in render
    self.content = self.rendered_content
  File "/usr/local/lib/python3.9/site-packages/rest_framework/response.py", line 70, in rendered_content
    ret = renderer.render(self.data, accepted_media_type, context)
  File "/usr/local/lib/python3.9/site-packages/rest_framework_swagger/renderers.py", line 54, in render
    self.set_context(data, renderer_context)
  File "/usr/local/lib/python3.9/site-packages/rest_framework_swagger/renderers.py", line 68, in set_context
    renderer_context['spec'] = OpenAPIRenderer().render(
  File "/usr/local/lib/python3.9/site-packages/rest_framework_swagger/renderers.py", line 34, in render
    return OpenAPICodec().encode(data, **options)
  File "/usr/local/lib/python3.9/site-packages/rest_framework_swagger/renderers.py", line 16, in encode
    raise TypeError('Expected a `coreapi.Document` instance')

Exception Type: TypeError at /
Exception Value: Expected a `coreapi.Document` instance

问题原因 #

rest_framework_swagger是已停止维护的旧库，仅支持Django REST Framework（DRF）3.x版本的coreapi格式接口文档。而Django 4.1搭配的DRF版本已升级至3.14+，新版本DRF默认生成OpenAPI 3格式的schema，不再返回coreapi.Document实例，导致旧库无法解析。

解决方法 #

方案1：改用维护中的Swagger库（推荐） #

使用drf-yasg或drf-spectacular，这两个库支持最新版Django和DRF，功能更完善。以drf-yasg为例：

1. 安装库：

pip install drf-yasg

2. 在settings.py的INSTALLED_APPS中添加：

INSTALLED_APPS = [
    # ... 其他已有应用
    'drf_yasg',
]

3. 修改urls.py：

from django.urls import path
from djangofun import views
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
from rest_framework import permissions

schema_view = get_schema_view(
   openapi.Info(
      title="API",
      default_version='v1',
      description="API接口文档",
   ),
   public=True,
   permission_classes=[permissions.AllowAny],
)

urlpatterns = [
    path('', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('hello/', views.hello)
]

启动服务后访问首页，即可正常显示Swagger UI界面。

方案2：降级DRF并安装依赖（不推荐） #

若坚持使用rest_framework_swagger，需降级DRF至3.10.x版本，并安装coreapi依赖：

1. 降级DRF：

pip install djangorestframework==3.10.3

2. 安装coreapi：

pip install coreapi

3. 保持原代码不变，重启服务即可正常显示Swagger UI。

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