FastAPI使用get_swagger_ui_html后出现多余Server选项的解决问询

在FastAPI 0.111.0中，通过get_swagger_ui_html自定义文档样式并添加额外HTML内容后，点击文档中的「Try it out」按钮时会显示操作级别的「Servers」选项，而默认文档不会出现这个问题。以下是无需依赖CSS隐藏的正规解决方案：

方案1：通过Swagger UI配置直接隐藏 #

Swagger UI 5.x版本官方提供了showOperationServers配置参数，可直接设置为false来隐藏操作级的Servers选项，只需在swagger_ui_parameters中添加该配置：

@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    swagger_ui_content = get_swagger_ui_html(
        openapi_url=app.openapi_url,
        swagger_ui_parameters={
            "syntaxHighlight": False,
            "defaultModelsExpandDepth": -1,
            "showOperationServers": False  # 新增配置项
        },
        title=app.title,
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
        swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
    )
    html_content = f'{swagger_ui_content.body.decode("utf-8")}'
    return HTMLResponse(html_content)

这是最直接的前端配置方案，通过官方参数控制渲染逻辑，符合Swagger UI的设计规范。

方案2：从OpenAPI Schema源头上移除操作级Servers字段 #

如果希望彻底消除该选项的数据源，可以重写FastAPI的openapi方法，遍历所有接口操作并删除其servers属性：

from fastapi import FastAPI
from fastapi.responses import HTMLResponse
from fastapi.openapi.docs import get_swagger_ui_html, get_swagger_ui_oauth2_redirect_html
import uvicorn

app = FastAPI(
    docs_url=None,
    description='some description',
    title='a title',
    version="1.0.0",
)

@app.get("/dummy_endpoint")
async def endpoint():
    return 'woohoo'

# 自定义OpenAPI生成逻辑，移除操作级servers
def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = app.openapi()
    # 遍历所有路径和接口操作
    for path_item in openapi_schema.get("paths", {}).values():
        for operation in path_item.values():
            # 删除操作级的servers字段
            operation.pop("servers", None)
    app.openapi_schema = openapi_schema
    return openapi_schema

app.openapi = custom_openapi

@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    swagger_ui_content = get_swagger_ui_html(
        openapi_url=app.openapi_url,
        swagger_ui_parameters={
            "syntaxHighlight": False,
            "defaultModelsExpandDepth": -1
        },
        title=app.title,
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
        swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
    )
    html_content = f'{swagger_ui_content.body.decode("utf-8")}'
    return HTMLResponse(html_content)

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)

该方案从API定义的源头上移除了操作级Servers的配置，Swagger UI因无对应数据自然不会渲染该选项。

方案3：使用FastAPI内置的Swagger UI版本 #

如果不需要依赖外部的Swagger UI资源，可以去掉swagger_js_url和swagger_css_url参数，使用FastAPI默认集成的Swagger UI版本，它会自动隐藏操作级Servers选项：

@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    swagger_ui_content = get_swagger_ui_html(
        openapi_url=app.openapi_url,
        swagger_ui_parameters={
            "syntaxHighlight": False,
            "defaultModelsExpandDepth": -1
        },
        title=app.title,
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        # 移除外部Swagger UI的URL配置，使用内置版本
    )
    html_content = f'{swagger_ui_content.body.decode("utf-8")}'
    return HTMLResponse(html_content)

FastAPI默认集成的Swagger UI已预配置了隐藏操作级Servers的参数，能保持和默认文档一致的行为。

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