配置 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 来禁用它：

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 参数文档。

仅限 JavaScript 的设置

Swagger UI 还允许其他配置为 仅限 JavaScript 的对象（例如，JavaScript 函数）。

FastAPI 也包含了这些仅限 JavaScript 的 presets 设置：

presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIBundle.SwaggerUIStandalonePreset
]

这些是 JavaScript 对象，而不是字符串，因此你不能直接从 Python 代码中传递它们。

如果你需要使用像这样的仅限 JavaScript 的配置，你可以使用上述方法之一。覆盖所有 Swagger UI 的 路径操作 并手动编写所需的任何 JavaScript。