FastAPI路径操作配置：tags分组、summary描述与deprecated弃用教程

本节目标：学会用装饰器上的参数给每个接口加标签、说明文字、弃用标记，并把某些接口从文档里隐藏。

前面我们写的接口都能跑，但打开 /docs 自动文档时，所有接口挤在一起，没有分类，也没有像样的说明。FastAPI 让你在路径操作装饰器上直接配置这些元信息，让文档既好看又专业。

Note

下面所有参数都写在装饰器里（@app.get(...)），不是写在函数里。别和函数参数搞混了。

17-1 用 tags 给接口分组

当接口多了，把相关的归到一组很有必要。装饰器参数 tags 接收一个字符串列表（通常只放一个），用于给接口打标签。

from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", tags=["items"])
async def create_item(name: str) -> dict:
    return {"name": name}


@app.get("/items/", tags=["items"])
async def read_items() -> list:
    return [{"name": "苹果"}]


@app.get("/users/", tags=["users"])
async def read_users() -> list:
    return [{"name": "小明"}]

打开 /docs，你会看到接口被分成 “items” 和 “users” 两组，结构一目了然。

如果应用很大、标签很多，担心拼错字符串，可以用枚举（Enum）统一管理：

from enum import Enum
from fastapi import FastAPI

app = FastAPI()


class Tags(str, Enum):
    items = "items"
    users = "users"


@app.get("/items/", tags=[Tags.items])
async def read_items() -> list:
    return [{"name": "苹果"}]

因为 Tags 继承自 str，FastAPI 能直接识别，编辑器还能帮你自动补全标签名。

17-2 用 summary 写一句话摘要

summary 是接口在文档里显示的简短标题，一句话说清这个接口干嘛。

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/", summary="获取商品列表", tags=["items"])
async def read_items() -> list:
    return [{"name": "苹果"}]

不写 summary 时，FastAPI 会用函数名自动生成（比如 read_items）。但自己写一句中文摘要，文档可读性会好很多。

17-3 用 description 写详细说明

比 summary 更长一点的描述，用 description 参数：

from fastapi import FastAPI

app = FastAPI()


@app.get(
    "/items/",
    summary="获取商品列表",
    description="返回当前系统里所有商品的简要信息，支持分页参数。",
    tags=["items"],
)
async def read_items() -> list:
    return [{"name": "苹果"}]

17-4 用 docstring 写描述更省事

长描述写在 description 里会让代码很臃肿。FastAPI 支持直接从函数的**文档字符串（docstring）**读取描述，而且里面能写 Markdown，会被自动渲染。

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}", tags=["items"])
async def read_item(item_id: int) -> dict:
    """
    根据商品 ID 获取单个商品的详情。

    - **item_id**: 商品在数据库里的唯一编号
    - 返回商品的名称、价格等字段
    """
    return {"item_id": item_id}

打开 /docs，你会看到这段 Markdown 被漂亮地渲染出来。这比把长文本硬塞进 description 参数整洁多了。

17-5 用 response_description 描述响应

前面几个都是描述”接口本身”，而 response_description 描述的是”成功响应长什么样”。OpenAPI 规范要求每个接口都有一句响应描述，不写的话 FastAPI 会自动补一句 “Successful response”。

from fastapi import FastAPI

app = FastAPI()


@app.get(
    "/items/",
    tags=["items"],
    summary="获取商品列表",
    response_description="返回商品列表",
)
async def read_items() -> list:
    return [{"name": "苹果"}]

Tip

description 说的是接口整体（给开发者看的说明），response_description 说的是响应内容（给调用方看的返回说明），两者别弄反。

17-6 用 deprecated 标记弃用

有些老接口你不想删，又想提醒调用方”别再用啦”，就加 deprecated=True。文档里这个接口会被标灰、标注弃用，但接口本身仍然能正常访问。

from fastapi import FastAPI

app = FastAPI()


@app.get("/legacy/items/", tags=["legacy"], deprecated=True)
async def read_legacy_items() -> list:
    return [{"name": "旧版数据"}]


@app.get("/items/", tags=["items"])
async def read_items() -> list:
    return [{"name": "新版本数据"}]

这样前端看到旧接口被划掉，就知道该切到新接口了。

17-7 用 include_in_schema 隐藏接口

偶尔你会写一些内部接口（比如健康检查、运维脚本），不想让它们出现在公开文档里。把 include_in_schema=False 加上即可：

from fastapi import FastAPI

app = FastAPI()


@app.get("/internal/health", include_in_schema=False)
async def health_check() -> dict:
    return {"status": "ok"}

接口照常工作，但 /docs 和 /openapi.json 里都看不到它，适合放只对内部开放的端点。

17-8 综合示例：给一组接口做完整配置

把前面学到的参数组合到一个小应用里，体会文档是怎么被”打扮”出来的：

from enum import Enum
from fastapi import FastAPI

app = FastAPI()


class Tags(str, Enum):
    items = "items"
    legacy = "legacy"


@app.get(
    "/items/",
    tags=[Tags.items],
    summary="获取商品列表",
    response_description="返回商品列表",
)
async def read_items() -> list:
    """
    获取当前系统里所有商品。

    - 返回商品的名称与价格
    - 后续可加上分页参数
    """
    return [{"name": "苹果", "price": 5}]


@app.get(
    "/legacy/items/",
    tags=[Tags.legacy],
    deprecated=True,
    include_in_schema=False,
)
async def read_legacy_items() -> list:
    return [{"name": "旧版数据"}]

打开 /docs，/items/ 出现在 “items” 分组下，带摘要、带 Markdown 描述；旧接口被标记弃用且不在文档里出现。一个装饰器上的几行参数，就带来这么大的文档提升。

Tip

文档可读性直接影响团队协作效率。养成习惯：每个对外接口都配 tags 和 summary，复杂逻辑再补 docstring 说明。内部接口用 include_in_schema=False 收好。

这些配置项全部写在装饰器上，所以它们是”零侵入”的——你的函数体不需要改一行，纯粹靠元数据让文档变好。这也是 FastAPI 设计上很舒服的一点：业务代码和接口描述解耦，改文档不影响逻辑，改逻辑也不破坏文档。等应用变大，你还可以把这些装饰器参数集中管理，比如用枚举统一 tags、用常量统一 summary 前缀，进一步减少拼写错误。

另外，tags 在文档里的展示顺序，默认按你首次使用它的接口出现顺序排。想精确控制分组顺序，可以在创建 FastAPI 实例时通过 openapi_tags 参数显式声明标签列表及其描述。初学阶段先用默认的即可，等接口多到需要精细排序时再研究。

最后提醒一个容易混淆的点：deprecated=True 和 include_in_schema=False 的语义完全不同。前者是”还在文档里，但明确劝你别用”，适合有过渡期的接口；后者是”文档里彻底不出现”，适合本就不对外的内部端点。两者都不会影响接口能否被访问——想真正禁止访问，得靠权限校验或者直接删掉这个路径操作，光靠文档配置是拦不住请求的。

17-9 小结

路径操作配置都是装饰器参数，零侵入地提升文档质量：

tags 给接口分组，大项目可用 Enum 管理标签。
summary 是一句话摘要，description 是详细说明（也可写在 docstring 里，支持 Markdown）。
response_description 描述成功响应的内容。
deprecated=True 标记弃用，提醒调用方迁移。
include_in_schema=False 把内部接口从文档里隐藏。

把这些配置用起来，你的 /docs 立刻从”能看”变成”专业”。