目录
1. 交互式 API 文档简介
FastAPI 会自动为每个应用生成交互式的 API 文档，支持基于 OpenAPI 规范的文档生成。默认情况下，FastAPI 提供了两种形式的交互式文档：
- Swagger UI：这是一个基于 OpenAPI 的交互式文档，允许用户查看 API 端点、发送请求，并查看响应。
- ReDoc：这是另一种样式的文档，适合展示 API 的结构和详细信息。
这些文档的生成是完全自动化的，你只需要编写 API 代码，FastAPI 就会为你提供易于交互的文档界面。
2. Swagger UI
Swagger UI 提供了一个交互式的 API 文档界面，用户可以直接在文档中发送请求，查看响应数据。这对于 API 的开发、调试以及与其他开发人员的协作非常有用。
访问 Swagger UI：
FastAPI 默认启用 Swagger UI，你可以通过访问以下 URL 来查看交互式文档：
http://127.0.0.1:8000/docs
在这个界面中，你将看到所有定义的路由和方法。你可以点击每个端点查看请求和响应的示例，并通过文档中的 UI 发送请求。
使用 Swagger UI：
- 查看 API 端点： 在左侧，你可以看到所有的 API 路由及其详细信息。
- 发送请求： 每个路由下面都有一个 “Try it out” 按钮，点击后，可以输入参数并发送请求。
- 查看响应： 请求返回后，你可以查看响应的状态码、响应时间、返回的数据等。
3. ReDoc 文档
ReDoc 提供了一种简洁、清晰的文档展示方式，适用于查看 API 的结构和详细信息。与 Swagger UI 相比，ReDoc 更加注重文档的层次结构和可读性。
访问 ReDoc 文档：
你可以通过以下 URL 访问 FastAPI 自动生成的 ReDoc 文档：
http://127.0.0.1:8000/redoc
ReDoc 的特点：
- 清晰的 API 结构： ReDoc 会以树状结构展示 API 的各个部分，包括路由、请求方法、请求体、响应等。
- 易于导航： 你可以通过左侧的导航栏快速跳转到 API 中的任何一个部分。
- 查看详细信息： 每个请求方法的详细信息都可以展开查看，特别适合需要了解 API 详细数据结构的开发者。
4. 定制文档
FastAPI 允许你定制自动生成的 API 文档。你可以自定义标题、描述、版本信息、接口描述等内容，以下是一些常见的定制方式：
设置应用的文档信息：
from fastapi import FastAPI
app = FastAPI(
title="我的 FastAPI 应用",
description="这是一个使用 FastAPI 构建的示例应用。",
version="1.0.0",
docs_url="/docs", # Swagger UI 文档的路径
redoc_url="/redoc", # ReDoc 文档的路径
)
通过以上配置，你可以自定义应用的标题、描述、版本号，并控制文档路径。如果需要关闭 Swagger UI 或 ReDoc 文档，也可以通过设置 None 来禁用它们：
app = FastAPI(docs_url=None, redoc_url=None) # 禁用文档
自定义文档内容：
你还可以为不同的 API 路由或请求方法添加更多的信息，比如描述、参数说明等：
@app.get("/items/{item_id}", summary="获取指定 ID 的项目", description="通过项目 ID 获取详细信息。")
def read_item(item_id: int):
return {"item_id": item_id}
发表回复