Django Rest Framework集成Swagger时版本验证失败求助

问题描述 #

用Django Rest Framework开发API，集成Swagger页面后出现报错：无法渲染定义，缺少有效的Swagger/OpenAPI版本字段（支持swagger: "2.0"或openapi: 3.0.n格式）。已参考官方文档配置了urls.py和swagger-ui.html，怀疑是OpenAPI Schema中的version="1.0.0"导致问题，但不确定是否有其他诱因。

相关代码如下：

urls.py 代码 #

from django.urls import path
urlpatterns = [
    ...
    ...
    path("openapi", get_schema_view(
            title="My api",
            description="API for me",
            version="1.0.0"
        ), name="openapi-schema"),
    path('swagger-ui/', TemplateView.as_view(
        template_name='swagger-ui.html',
        extra_context={'schema_url':'openapi-schema'}
    ), name='swagger-ui')
]

templates/swagger-ui.html 代码 #

<!DOCTYPE html>
<html>
  <head>
    <title>Swagger</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
    <script>
    const ui = SwaggerUIBundle({
        url: "{% url schema_url %}",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout",
        requestInterceptor: (request) => {
          request.headers['X-CSRFToken'] = "{{ csrf_token }}"
          return request;
        }
      })
    </script>
  </body>
</html>

解决步骤 #

1. 区分API版本与OpenAPI规范版本 #

你代码中get_schema_view里的version="1.0.0"是你的API自身的版本，而Swagger UI要求的是OpenAPI规范的版本（比如3.0.3），两者是不同概念。需要在get_schema_view中添加openapi_version参数指定规范版本。

修改后的urls.py代码：

from django.urls import path
from rest_framework.schemas import get_schema_view
from django.views.generic import TemplateView

urlpatterns = [
    # ... 保留其他路由
    path("openapi", get_schema_view(
            title="My api",
            description="API for me",
            version="1.0.0",  # 你的API版本，可自定义
            openapi_version="3.0.3"  # OpenAPI规范版本，必须为3.0.n格式
        ), name="openapi-schema"),
    path('swagger-ui/', TemplateView.as_view(
        template_name='swagger-ui.html',
        extra_context={'schema_url':'openapi-schema'}
    ), name='swagger-ui')
]

2. 验证Schema正确性 #

访问/openapi端点，确认返回的JSON数据中包含"openapi": "3.0.3"字段，这是Swagger UI识别规范版本的关键。

3. 缓存与路由检查 #

如果修改后仍报错，可尝试清除浏览器缓存，或确认swagger-ui.html中的schema_url是否正确指向了openapi-schema路由（确保路由名称和参数匹配）。

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