自动 API 文档：Swagger UI 和 ReDoc

引言

FastAPI 是一个现代、快速（高性能）的Web框架，用于构建API。它最大的亮点之一是自动生成交互式API文档，无需额外配置。这主要基于OpenAPI标准，并集成了两个流行的文档界面：Swagger UI 和 ReDoc。通过本教程，你将学会如何利用这些工具提升API的可用性和开发效率。

为什么自动API文档如此重要？

• 开发者友好：API文档是开发者使用API的桥梁，自动生成确保文档与代码同步，避免手动维护的误差。
• 交互式测试：用户可以直接在浏览器中测试API端点，无需编写额外代码，加快调试和集成过程。
• 标准化：基于OpenAPI规范，确保文档格式统一，兼容各种工具和平台。
• 提升效率：减少文档编写时间，让开发者更专注于核心功能开发。

Swagger UI

什么是Swagger UI？

Swagger UI 是一个开源工具，用于可视化OpenAPI规范的文档。它提供了一个用户友好的界面，可以查看API端点、参数、响应模型，并进行交互式测试。FastAPI默认集成Swagger UI，使其成为API开发和测试的理想选择。

如何访问Swagger UI？

在FastAPI应用中，默认情况下，Swagger UI会自动启用。访问方式非常简单：

1. 本地开发环境：运行FastAPI应用后，打开浏览器，访问 http://localhost:8000/docs。
   • 注意：默认端口是8000。如果你的应用使用其他端口（例如，通过 uvicorn 命令指定 --port 参数），请相应调整URL，如 http://localhost:8080/docs。
2. 部署环境：在部署的服务器上，只需访问应用根路径下的 /docs 路径，例如 https://your-api.com/docs。

示例代码：快速上手

首先，确保安装了FastAPI和uvicorn（ASGI服务器）。创建一个简单的FastAPI应用：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

保存为 main.py，然后在终端运行：

uvicorn main:app --reload

打开浏览器访问 http://localhost:8000/docs，你将看到Swagger UI界面显示所有API端点。

Swagger UI 功能详解

• 端点列表：界面左侧列出所有定义的API端点，按路径分组，清晰可见。
• 详细信息：点击任意端点，右侧面板展示详细信息，包括：
  • 请求方法（如GET、POST）。
  • 路径和路径参数。
  • 查询参数、请求体模型（如果适用）。
  • 响应模型和状态码。
• 交互式测试：在详细信息面板中，你可以直接填写参数（如路径参数 item_id 或查询参数 q），然后点击“Execute”按钮发送请求。界面会显示响应数据、状态码和响应头，便于实时调试。
• 认证支持：如果API需要认证（如Bearer Token），Swagger UI 支持配置认证头。在界面顶部点击“Authorize”按钮，输入认证信息即可。
• 模型可视化：对于复杂的数据模型，Swagger UI 以JSON Schema形式展示，帮助理解数据结构。

自定义Swagger UI

FastAPI允许自定义Swagger UI的某些设置，以适应特定需求：

• 更改文档标题：在 FastAPI() 初始化时传递 title 参数。
• 修改访问路径：使用 docs_url 参数指定自定义路径。
• 隐藏端点：在路径操作装饰器中，设置 include_in_schema=False 可以隐藏特定端点。
• 添加描述：使用OpenAPI配置或Pydantic模型添加更多文档细节。

示例代码：

from fastapi import FastAPI

app = FastAPI(
    title="我的API",
    description="这是一个示例API文档",
    docs_url="/custom-docs",  # 自定义Swagger UI访问路径
    redoc_url="/custom-redoc"  # 自定义ReDoc访问路径
)

@app.get("/", include_in_schema=False)  # 隐藏根端点
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

运行后，Swagger UI将访问 /custom-docs。

常见问题与解决

• 文档不显示：检查应用是否正确运行（使用 uvicorn main:app --reload），并确保没有端口冲突。如果自定义了路径，请访问正确的URL。
• 界面加载慢：这通常是由于网络或浏览器缓存问题；尝试刷新页面或清除缓存。
• 认证配置失败：确保在Swagger UI的“Authorize”对话框中正确输入认证信息，如Token类型和值。

ReDoc

什么是ReDoc？

ReDoc 是另一个用于渲染OpenAPI规范的文档生成器。它提供一个简洁、美观的文档界面，专注于阅读文档而非交互式测试。FastAPI默认集成ReDoc，为API用户提供另一种文档体验。

如何访问ReDoc？

访问方式类似于Swagger UI：

• 本地开发环境：访问 http://localhost:8000/redoc。
• 部署环境：访问应用根路径下的 /redoc 路径，例如 https://your-api.com/redoc。

ReDoc 功能详解

• 美观界面：设计简洁，使用深色主题，提升可读性，适合长时间阅读。
• 响应式布局：在桌面和移动设备上都能良好显示，侧边栏导航方便浏览。
• 快速导航：提供搜索功能和目录结构，帮助用户快速定位API端点。
• 模型展示：以清晰的方式展示请求和响应模型，支持嵌套结构和示例。
• 对比Swagger UI：ReDoc 更侧重于文档展示和阅读，而Swagger UI 更侧重于交互式测试和开发调试。

自定义ReDoc

与Swagger UI类似，可以自定义ReDoc的设置：

• 修改访问路径：在 FastAPI() 初始化时设置 redoc_url 参数。
• 禁用ReDoc：设置 redoc_url=None 即可禁用ReDoc文档。

示例代码（与上文自定义示例相同）：

app = FastAPI(redoc_url="/custom-redoc")

运行后，ReDoc将访问 /custom-redoc。

Swagger UI 与 ReDoc 比较

选择建议：

• 如果你是API开发者或需要测试API，推荐使用Swagger UI，因为它提供交互式功能。
• 如果你是为最终用户或团队提供文档，ReDoc 可能更合适，因为它界面更友好且易于阅读。
• 在实际项目中，可以同时启用两者，让用户根据需求选择访问路径。

总结与最佳实践

FastAPI的自动API文档功能极大地简化了API开发流程。通过Swagger UI和ReDoc，你可以：

1. 快速生成文档：无需手动编写，文档随代码自动更新。
2. 提升协作效率：团队可以轻松查看和测试API端点。
3. 增强用户体验：提供交互式测试和美观的阅读界面。

下一步学习

• 深入学习OpenAPI：探索如何在FastAPI中添加更多OpenAPI元数据，如描述、示例和错误处理。
• 自定义文档：学习使用Pydantic模型和依赖注入来丰富文档内容。
• 安全集成：了解如何在文档中配置OAuth2或其他认证方式。
• 部署优化：在部署环境中，考虑禁用文档（设置 docs_url=None 和 redoc_url=None）以提高安全性，或使用CDN加速文档加载。

常见问题集锦

• 如何完全禁用自动文档？ 在 FastAPI() 初始化时设置 docs_url=None 和 redoc_url=None。
• 文档不更新怎么办？ 确保应用在开发模式下运行（使用 --reload 标志），代码更改后文档会自动刷新。
• 如何添加API描述？ 在路径操作函数中使用docstring或在装饰器中添加 summary 和 description 参数。
• Swagger UI和ReDoc冲突吗？ 不冲突，它们是独立的界面，可以同时启用。

通过本教程，你应该已经掌握了FastAPI中自动API文档的基础知识。实践是巩固学习的最佳方式——尝试创建一个简单的API项目，探索Swagger UI和ReDoc的更多功能，并分享给你的团队吧！如有问题，参考FastAPI官方文档或社区资源获取更多帮助。