问题：FastAPI Swagger 如何添加 Authorization Header？

Question

在使用 FastAPI 开发 RESTful API 时，如何在 Swagger UI 中添加 Authorization Header 以便进行接口测试，是开发者常遇到的问题。FastAPI 基于 Starlette 和 Pydantic，提供了内置的 Swagger（即 Swagger UI）支持，但默认情况下并不会自动包含认证所需的 Header，如 `Authorization: Bearer `。开发者需要通过配置 `Security` 组件和 `OAuth2PasswordBearer` 等机制，手动在接口文档中添加认证支持。本文将详解如何正确配置 FastAPI，使得 Swagger UI 能够识别并携带 Authorization Header，从而方便接口调试和测试。

Answer 1

在 FastAPI 中配置 Swagger UI 添加 Authorization Header

在使用 FastAPI 开发 RESTful API 时，如何在 Swagger UI 中添加 Authorization Header 以便进行接口测试，是开发者常遇到的问题。FastAPI 基于 Starlette 和 Pydantic，提供了内置的 Swagger（即 Swagger UI）支持，但默认情况下并不会自动包含认证所需的 Header，如 Authorization: Bearer <token>。开发者需要通过配置 Security 组件和 OAuth2PasswordBearer 等机制，手动在接口文档中添加认证支持。

1. 基础概念：Swagger UI 与 FastAPI 的集成机制

FastAPI 使用的是 Swagger UI 来提供 API 文档可视化界面。它基于 OpenAPI 规范生成接口文档，并允许开发者进行接口测试。默认情况下，Swagger UI 不会自动识别认证信息，因此需要开发者手动添加安全组件。

FastAPI 提供了内置的 Security 模块，可以结合 OAuth2PasswordBearer 或其他认证机制，在接口中声明安全依赖项，从而让 Swagger UI 显示认证输入框。

2. 实现步骤：如何在 Swagger UI 中添加 Authorization Header

以下是一个典型的实现流程：

1. 定义安全组件（如 OAuth2PasswordBearer）
2. 在接口路径中使用 Security(...) 声明安全依赖
3. 运行服务后，Swagger UI 将显示认证输入框

3. 示例代码：添加 Bearer Token 认证支持

以下是一个完整的示例代码：

from fastapi import Depends, FastAPI, Security
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.get("/items/")
async def read_items(token: str = Depends(oauth2_scheme)):
    return {"token": token}

运行该服务后访问 http://localhost:8000/docs，Swagger UI 会自动显示一个 “Authorize” 按钮，允许你输入 Bearer Token。

4. 进阶技巧：自定义安全组件与多认证机制支持

FastAPI 支持多种安全机制，包括：

• OAuth2 with Bearer Token
• API Key in Header or Query
• HTTP Basic Auth
• JWT 验证

开发者可以通过继承 SecurityBase 类或使用 Security 组合多个认证机制。

5. 配置细节：Swagger UI 的 OpenAPI 文档生成逻辑

FastAPI 会根据接口定义自动生成 OpenAPI 文档。当接口中使用了 Depends 或 Security 声明安全依赖时，FastAPI 会自动在 OpenAPI 文档中添加 securitySchemes 和 security 字段。

例如，使用 OAuth2PasswordBearer 会生成如下 OpenAPI 配置片段：

"components": {
    "securitySchemes": {
        "OAuth2PasswordBearer": {
            "type": "oauth2",
            "flows": {
                "password": {
                    "tokenUrl": "token",
                    "scopes": {}
                }
            }
        }
    }
}

6. 常见问题与解决方案

问题	解决方案
Swagger UI 中没有显示认证输入框	检查接口是否正确使用了 Depends(oauth2_scheme) 或其他安全依赖
Token 验证失败	确保后端逻辑中正确解析了 Token，并处理异常情况
多认证机制冲突	使用 Security 显式声明多个安全依赖，并在 OpenAPI 中合理配置

7. 架构图示：FastAPI 安全组件与 Swagger UI 的协作流程

graph TD
    A[FastAPI 应用] --> B[定义安全组件]
    B --> C[接口使用 Security]
    C --> D[生成 OpenAPI 文档]
    D --> E[Swagger UI 显示认证输入]
    E --> F[用户输入 Token]
    F --> G[发送带 Authorization Header 的请求]