新乡微信网站建设wordpress仿安卓主题下载

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 FastAPIapp = 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 FastAPIapp = 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 OpenAPIapp = 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 文档：

1. 打开 Postman。
2. 在左侧菜单栏选择 Import，然后选择 Link。
3. 输入 FastAPI 提供的 OpenAPI JSON 地址（通常是 http://127.0.0.1:8000/openapi.json）。
4. 点击 Continue，Postman 将导入 API 文档并生成接口请求模板。

FastAPI 提供了一个非常方便且强大的功能：自动生成 API 文档。通过内置的 Swagger UI 和 ReDoc，你可以轻松查看、测试和管理 API 接口。文档会自动根据代码的变化更新，这减少了手动编写文档的工作量。此外，FastAPI 还支持高度自定义 OpenAPI 文档，让开发者可以灵活配置 API 文档的内容。

借助 FastAPI 自动文档功能，开发者可以大大提升工作效率，更好地与前端开发人员协作，快速构建和维护 API。

---

这个博客草稿介绍了 FastAPI 的自动文档生成功能，以及如何使用 Swagger UI 和 ReDoc 查看和交互文档。你可以根据需求进一步扩展，介绍更复杂的自定义文档生成或集成其他工具的使用。