在Django REST Framework的Swagger页面添加多格式Schema链接

一、修复多Schema仅最后一个生效的问题 #

SwaggerUIBundle的url参数仅支持单个地址，重复赋值会覆盖之前的配置。要实现多Schema切换，需改用urls数组参数，每个元素包含Schema的名称和地址：

在你自定义的swagger-ui.html模板中，找到SwaggerUIBundle初始化代码，修改为：

const ui = SwaggerUIBundle({
  // 替换原有的单个url配置为urls数组
  urls: [
    {
      name: 'JSON格式Schema',
      url: "{% url 'schema-json' %}"
    },
    {
      name: 'YAML格式Schema',
      url: "{% url 'schema-yaml' %}"
    }
  ],
  dom_id: '#swagger-ui',
  deepLinking: true,
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  layout: "StandaloneLayout"
  // 保留你原有的其他配置项
});

二、在Swagger页面顶部添加Schema下载链接 #

在自定义模板的Swagger UI容器上方，添加一个包含下载链接的区块，使用Django模板标签反向生成Schema的访问地址：

<!-- 在<div id="swagger-ui"></div>之前添加以下代码 -->
<div style="padding: 1rem 2rem; background-color: #f8f9fa; border-bottom: 1px solid #e9ecef;">
  <a href="{% url 'schema-json' %}" target="_blank" style="margin-right: 1.5rem; color: #0d6efd;">
    下载JSON格式Schema
  </a>
  <a href="{% url 'schema-yaml' %}" target="_blank" style="color: #0d6efd;">
    下载YAML格式Schema
  </a>
</div>

<div id="swagger-ui"></div>

三、确保Django路由配置正确 #

在项目的urls.py中，需正确配置drf-spectacular的Schema路由，保证模板中的{% url %}标签能正确反向解析：

from django.urls import path
from drf_spectacular.views import (
    SpectacularAPIView,
    SpectacularJSONAPIView,
    SpectacularYAMLAPIView,
    SpectacularSwaggerView,
)

urlpatterns = [
    # 其他路由...
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/schema/json/', SpectacularJSONAPIView.as_view(), name='schema-json'),
    path('api/schema/yaml/', SpectacularYAMLAPIView.as_view(), name='schema-yaml'),
    path('api/docs/', SpectacularSwaggerView.as_view(template_name='swagger-ui.html'), name='swagger-ui'),
]

完成以上配置后，Swagger页面顶部会出现两个下载链接，同时顶部的下拉菜单可以切换JSON/YAML两种Schema视图，不会再出现仅最后一个Schema生效的问题。

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