配置 Swagger UI¶
你可以配置一些额外的 Swagger UI 参数.
如果需要配置它们,可以在创建 FastAPI()
应用对象时或调用 get_swagger_ui_html()
函数时传递 swagger_ui_parameters
参数。
swagger_ui_parameters
接受一个直接传递给 Swagger UI的字典,包含配置参数键值对。
FastAPI会将这些配置转换为 JSON,使其与 JavaScript 兼容,因为这是 Swagger UI 需要的。
不使用语法高亮¶
比如,你可以禁用 Swagger UI 中的语法高亮。
当没有改变设置时,语法高亮默认启用:
但是你可以通过设置 syntaxHighlight
为 False
来禁用 Swagger UI 中的语法高亮:
from fastapi import FastAPI
app = FastAPI(swagger_ui_parameters={"syntaxHighlight": False})
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
...在此之后,Swagger UI 将不会高亮代码:
改变主题¶
同样地,你也可以通过设置键 "syntaxHighlight.theme"
来设置语法高亮主题(注意中间有一个点):
from fastapi import FastAPI
app = FastAPI(swagger_ui_parameters={"syntaxHighlight.theme": "obsidian"})
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
这个配置会改变语法高亮主题:
改变默认 Swagger UI 参数¶
FastAPI 包含了一些默认配置参数,适用于大多数用例。
其包括这些默认配置参数:
swagger_ui_default_parameters: Annotated[
Dict[str, Any],
Doc(
"""
Default configurations for Swagger UI.
You can use it as a template to add any other configurations needed.
"""
),
] = {
"dom_id": "#swagger-ui",
"layout": "BaseLayout",
"deepLinking": True,
"showExtensions": True,
"showCommonExtensions": True,
}
你可以通过在 swagger_ui_parameters
中设置不同的值来覆盖它们。
比如,如果要禁用 deepLinking
,你可以像这样传递设置到 swagger_ui_parameters
中:
from fastapi import FastAPI
app = FastAPI(swagger_ui_parameters={"deepLinking": False})
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
其他 Swagger UI 参数¶
查看其他 Swagger UI 参数,请阅读 docs for Swagger UI parameters。
JavaScript-only 配置¶
Swagger UI 同样允许使用 JavaScript-only 配置对象(例如,JavaScript 函数)。
FastAPI 包含这些 JavaScript-only 的 presets
设置:
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
这些是 JavaScript 对象,而不是字符串,所以你不能直接从 Python 代码中传递它们。
如果你需要像这样使用 JavaScript-only 配置,你可以使用上述方法之一。覆盖所有 Swagger UI path operation 并手动编写任何你需要的 JavaScript。