笙亿网络策划

FastAPI怎么生成交互式API文档？

约 6 分钟读完 7 阅
文章导读
FastAPI 基于代码中的类型注解自动生成交互式 API 文档，默认提供 Swagger UI 和 ReDoc 两种界面。开发者可以直接在文档中测试 API，无需额外的工具。
📋 目录
  1. 壹 访问 API 文档
  2. 贰 Swagger UI
  3. 叁 ReDoc
  4. 肆 OpenAPI 规范
  5. 伍 自定义 API 文档信息
  6. 陆 实例
  7. 柒 为路由添加文档信息
  8. 捌 实例
  9. 玖 使用 tags 分组
  10. 拾 实例
A A

FastAPI 交互式 API 文档

FastAPI 基于代码中的类型注解自动生成交互式 API 文档，默认提供 Swagger UI 和 ReDoc 两种界面。开发者可以直接在文档中测试 API，无需额外的工具。

访问 API 文档

运行 FastAPI 应用后，访问以下地址查看文档：

地址文档类型特点
http://127.0.0.1:8000/docsSwagger UI可交互测试，点击"Try it out"即可发送请求
http://127.0.0.1:8000/redocReDoc阅读体验好，适合浏览和查阅 API 定义
http://127.0.0.1:8000/openapi.jsonOpenAPI JSON原始的 OpenAPI 规范 JSON，可供工具消费

Swagger UI

Swagger UI 提供了直观的用户界面，可以直接在浏览器中测试 API：

测试 API 的步骤

  1. 点击要测试的路由，展开详情
  2. 点击 "Try it out" 按钮
  3. 填写参数值
  4. 点击 "Execute" 按钮发送请求
  5. 查看响应结果

ReDoc

ReDoc 注重文档的可读性，适合浏览 API 定义：

OpenAPI 规范

FastAPI 使用 OpenAPI 标准将 API 转换为"模式"（Schema）。访问 http://127.0.0.1:8000/openapi.json 可以查看原始的 OpenAPI JSON：

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/{item_id}": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response"
                    }
                }
            }
        }
    }
}

OpenAPI 规范的用途：

  • 驱动 Swagger UI 和 ReDoc 文档系统
  • 自动生成各种语言的客户端代码
  • 与 API 测试工具（如 Postman）集成
  • 兼容大量第三方工具和平台

自定义 API 文档信息

创建 FastAPI 实例时，可以自定义文档的元数据：

实例

from fastapi import FastAPI

app = FastAPI(
    title="我的 API",                    # API 标题
    description="这是一个示例 API，展示文档自定义功能",  # API 描述
    version="1.0.0",                    # API 版本
    terms_of_service="http://example.com/terms/",  # 服务条款 URL
    contact={                           # 联系信息
        "name": "开发者",
        "url": "http://example.com/contact/",
        "email": "dev@example.com",
    },
    license_info={                      # 许可证信息
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

为路由添加文档信息

可以在装饰器和函数中为每个路由添加详细的文档信息：

实例

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get(
    "/items/{item_id}",
    summary="获取商品信息",              # 简短摘要
    description="根据商品 ID 获取商品的详细信息",  # 详细描述
    response_description="商品信息对象",   # 响应描述
    tags=["商品管理"],                   # 分组标签
)
async def read_item(
    item_id: Annotated[int, Path(ge=1, description="商品ID")],
    q: Annotated[str | None, Query(description="搜索关键词")] = None,
):
    """
    获取商品信息：

    - **item_id**: 商品的唯一标识符
    - **q**: 可选的搜索关键词
    """
    return {"item_id": item_id, "q": q}

文档参数说明：

参数位置说明
summary装饰器路由的简短摘要，显示在路由列表中
description装饰器路由的详细描述，支持 Markdown
response_description装饰器响应的描述
tags装饰器路由分组，在文档中按标签分类显示
docstring函数体函数的文档字符串，会作为描述显示

如果同时设置了 description 和函数的 docstring，description 优先生效。docstring 支持 Markdown 格式，适合编写较长的说明。

使用 tags 分组

tags 参数可以将相关的路由归为一组，在文档中更清晰地展示：

实例

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/", tags=["用户管理"])
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]


@app.get("/items/", tags=["商品管理"])
async def read_items():
    return [{"name": "Foo"}, {"name": "Bar"}]

在 Swagger UI 中，路由会按标签分组显示。

禁用文档

在生产环境中，你可能想禁用自动文档：

实例

from fastapi import FastAPI

# 禁用文档
app = FastAPI(docs_url=None, redoc_url=None)

小结

  • FastAPI 自动生成 Swagger UI 和 ReDoc 两种交互式文档
  • 文档内容基于代码中的类型注解自动生成，代码更新文档自动同步
  • 使用 title、description、tags 等参数自定义文档信息
  • 函数的 docstring 也会出现在文档中
  • 生产环境可通过 docs_url=None 禁用文档