10 FastAPI 的自动文档

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 查看和交互文档。你可以根据需求进一步扩展，介绍更复杂的自定义文档生成或集成其他工具的使用。
在这里插入图片描述