如何在FastAPI的Swagger UI页面插入自定义JavaScript代码？

问题原因 #

你之前的代码错误地用自定义脚本替换了Swagger UI的核心JavaScript文件（swagger_js_url参数是指定Swagger UI依赖的核心bundle文件），这会导致Swagger UI本身无法正常加载，自然自定义脚本也无法生效。

正确解决方案 #

方法1：修改返回的HTML内容，追加自定义脚本 #

保留官方Swagger UI的核心资源，在生成的HTML末尾插入自定义脚本（外部文件或内联代码均可）：

from fastapi import FastAPI, HTMLResponse
from fastapi.staticfiles import StaticFiles
from fastapi.openapi.docs import get_swagger_ui_html

api = FastAPI(docs_url=None)
# 挂载静态文件目录，用于存放自定义脚本
api.mount("/static", StaticFiles(directory="static"), name="static")

@api.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    # 生成默认的Swagger UI HTML
    base_html = get_swagger_ui_html(
        openapi_url=api.openapi_url,
        title=f"{api.title} - Swagger UI",
        oauth2_redirect_url=api.swagger_ui_oauth2_redirect_url,
        # 保留官方核心JS和CSS，也可以替换成本地文件
        swagger_js_url="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
        swagger_css_url="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
    )
    
    # 自定义脚本：可以是外部文件引用+内联代码
    custom_script = """
    <!-- 加载外部自定义脚本 -->
    <script src="/static/custom_script.js"></script>
    <!-- 内联脚本 -->
    <script>
        // 页面加载完成后执行
        window.addEventListener('load', () => {
            alert('Swagger UI自定义脚本生效！');
            // 示例：修改Swagger UI标题样式
            const header = document.querySelector('.swagger-ui .topbar');
            if (header) header.style.backgroundColor = '#2c3e50';
        });
    </script>
    """
    
    # 将自定义脚本追加到HTML末尾
    modified_html = base_html.content.decode("utf-8") + custom_script
    return HTMLResponse(content=modified_html, status_code=200)

方法2：使用extra_script参数（适用于FastAPI 0.95+版本） #

新版本的FastAPI在get_swagger_ui_html中提供了extra_script参数，可直接传入内联脚本代码，会自动插入到Swagger UI初始化完成后的位置：

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from fastapi.openapi.docs import get_swagger_ui_html

api = FastAPI(docs_url=None)
api.mount("/static", StaticFiles(directory="static"), name="static")

@api.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=api.openapi_url,
        title=f"{api.title} - Swagger UI",
        oauth2_redirect_url=api.swagger_ui_oauth2_redirect_url,
        # 传入内联自定义脚本
        extra_script="""
            alert('worked!');
            // 动态加载外部脚本
            const script = document.createElement('script');
            script.src = '/static/custom_script.js';
            script.onload = () => console.log('自定义脚本加载完成');
            document.body.appendChild(script);
        """
    )

注意事项 #

• 不要替换swagger_js_url和swagger_css_url为自定义文件，除非你已经完整复制了Swagger UI的核心资源到本地；
• 自定义脚本中如果需要操作Swagger UI的DOM，建议监听load事件或使用Swagger UI的官方事件钩子（比如ui.init），确保DOM已加载完成；
• 静态文件目录static需要和你的Python脚本同级，且里面存放custom_script.js文件。

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