FastAPI 是一个功能强大且易于使用的 Web 框架,它的最大亮点之一就是内置的 自动文档生成 功能。通过集成 Swagger UI 和 ReDoc,FastAPI 可以自动为我们的 API 生成交互式文档。这不仅使得开发者能够更快速地了解和测试 API,还能够为前端开发人员和其他使用者提供清晰、准确的接口说明。
本文将介绍如何使用 FastAPI 自动生成 API 文档,如何使用 Swagger UI 和 ReDoc 来查看和交互 API 文档,以及文档如何自动更新。
1. 快速入门:安装 FastAPI 和 Uvicorn
首先,如果你还没有安装 FastAPI 和 Uvicorn,请使用以下命令进行安装:
pip install fastapi uvicorn
然后,可以使用 Uvicorn 启动 FastAPI 应用:
uvicorn main:app --reload
在这个命令中:
main
是 Python 文件的名称(即main.py
)。app
是 FastAPI 实例的变量名。
2. FastAPI 的自动文档
FastAPI 使用 OpenAPI 规范来自动生成 API 文档。OpenAPI 是一个标准化的接口描述语言,FastAPI 会根据定义的路由、请求参数、响应等自动生成接口文档。
2.1 使用 Swagger UI 查看文档
FastAPI 默认启用了 Swagger UI,它提供了一个交互式的用户界面,用于查看和测试 API。
假设我们有以下简单的 FastAPI 应用:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: int, query: str = None):
return {"item_id": item_id, "query": query}
启动应用后,访问 http://127.0.0.1:8000/docs
就可以看到 Swagger UI 的界面,其中包含了 GET /items/{item_id}
路由的详细信息。
2.1.1 Swagger UI 的特点
- 交互式测试:你可以直接在文档界面上测试 API。只需点击一个路由,输入参数,然后点击 “Execute” 即可发送请求并查看响应。
- 实时更新:当你更改 FastAPI 应用时,Swagger UI 会自动更新文档,反映新的路由和参数。
- 自动生成:FastAPI 会自动根据 Python 函数的注解(如类型注解、默认值等)生成 API 文档,无需额外的注释或配置。
2.2 使用 ReDoc 查看文档
除了 Swagger UI,FastAPI 还内置了 ReDoc,它提供了另一种风格的 API 文档,适合那些更喜欢静态文档或需要生成 PDF 版本的用户。
访问 http://127.0.0.1:8000/redoc
即可看到 ReDoc 界面。
2.2.1 ReDoc 的特点
- 清晰简洁的界面:ReDoc 的界面较为简洁,适合查看大规模的 API 文档。
- 支持丰富的 OpenAPI 特性:ReDoc 提供了详细的 OpenAPI 规范支持,包括复杂的请求和响应结构、数据模型等。
2.3 自定义文档标题和描述
你可以在创建 FastAPI 应用时,使用 title
、description
、version
等参数来自定义 API 文档的标题、描述和版本。
from fastapi import FastAPI
app = FastAPI(
title="My API",
description="This is a very simple API for demonstration.",
version="1.0.0"
)
@app.get("/items/{item_id}")
async def read_item(item_id: int, query: str = None):
return {"item_id": item_id, "query": query}
启动应用后,访问 http://127.0.0.1:8000/docs
,你将看到自定义的文档标题和描述。
2.4 自动更新 API 文档
FastAPI 自动生成的 API 文档会根据应用代码的变化实时更新。以下是一些常见的更新内容:
- 新增路由:当你添加新的路由时,Swagger UI 和 ReDoc 会立即反映出来。
- 修改参数:当你修改路由的请求参数类型或描述时,文档会自动更新。
- 更新响应格式:如果你更新了响应体或错误码,文档也会自动更新。
2.5 自定义 OpenAPI 文档
如果需要更多的定制化,你可以通过 openapi_schema
或 openapi
属性修改 FastAPI 生成的 OpenAPI 文档。例如,可以添加额外的元数据、修改默认的响应状态码、定义统一的错误结构等。
from fastapi import FastAPI
from fastapi.openapi.models import OpenAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: int, query: str = None):
return {"item_id": item_id, "query": query}
# 自定义 OpenAPI 文档
@app.get("/custom_openapi")
async def custom_openapi():
custom_openapi_schema = OpenAPI(
title="Custom API",
version="2.0.0",
description="A custom API with modified OpenAPI schema.",
routes=app.routes
)
return custom_openapi_schema
3. 通过 OpenAPI 文档与前端进行协作
由于 FastAPI 自动生成的 API 文档遵循 OpenAPI 标准,你可以轻松地与前端开发人员协作。前端开发人员可以通过 Swagger UI 或 ReDoc 来查看 API 接口,并根据文档进行开发。甚至他们可以直接从 API 文档中获取接口参数、返回值类型、示例请求等信息。
4. 集成第三方工具
除了内置的 Swagger UI 和 ReDoc,FastAPI 也支持与其他工具进行集成。通过配置 OpenAPI,开发者可以使用像 Postman、Insomnia 这样的工具来导入 FastAPI 生成的 OpenAPI 文档进行接口测试和调试。
例如,可以使用 Postman 导入 OpenAPI 文档:
- 打开 Postman。
- 在左侧菜单栏选择 Import,然后选择 Link。
- 输入 FastAPI 提供的 OpenAPI JSON 地址(通常是
http://127.0.0.1:8000/openapi.json
)。 - 点击 Continue,Postman 将导入 API 文档并生成接口请求模板。
FastAPI 提供了一个非常方便且强大的功能:自动生成 API 文档。通过内置的 Swagger UI 和 ReDoc,你可以轻松查看、测试和管理 API 接口。文档会自动根据代码的变化更新,这减少了手动编写文档的工作量。此外,FastAPI 还支持高度自定义 OpenAPI 文档,让开发者可以灵活配置 API 文档的内容。
借助 FastAPI 自动文档功能,开发者可以大大提升工作效率,更好地与前端开发人员协作,快速构建和维护 API。
这个博客草稿介绍了 FastAPI 的自动文档生成功能,以及如何使用 Swagger UI 和 ReDoc 查看和交互文档。你可以根据需求进一步扩展,介绍更复杂的自定义文档生成或集成其他工具的使用。