fastapi之路径操作中的标签和摘要

Tags、Summary、Description

Tags

标签用于对 API 端点进行分类。在大型应用中，可能会有多个模块或组件，每个模块包含多个端点。通过使用标签，可以将相关的端点组织在一起，这样在自动生成的文档中就能够更容易地导航。

例如，所有与“物品”(items) 相关的操作可以使用相同的标签：
tags=["items"]
在文档界面中，所有标记为“items”的端点将被分组在一起，使得用户能够快速找到与物品操作相关的所有 API。

Summary

摘要提供了对 API 端点功能的简短说明。应当简洁明了，能够让开发者快速理解端点的基本功能。

summary="通过ID检索物品"
这个摘要告诉用户，此 API 端点的功能是通过物品的 ID 来检索物品。

Description

描述可以提供比摘要更详细的信息。这是解释端点如何工作、期望的输入、产生的输出以及任何特殊行为的好地方。
描述可以直接在函数的 docstring 中编写，FastAPI 会自动将其作为 API 文档的一部分

@app.get("/items/{item_id}", tags=["items"], summary="通过ID检索物品")
def read_item(item_id: int):
    """
    通过物品 ID 检索物品。

    - **item_id**: int - 要检索的物品的唯一标识符
    """
    return {"item_id": item_id}

示例

from fastapi import FastAPI
from pydantic import BaseModel
import uvicorn
import os

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str
    price: float


class User(BaseModel):
    username: str
    full_name: str
    email: str


@app.post("/items/", tags=["items"], summary="创建新物品", response_model=Item)
def create_item(item: Item):
    """
    创建一个新的物品记录。

    - **item**: Item - 必须提供物品的名称、描述和价格。
    """
    return item


@app.get("/items/{item_id}", tags=["items"], summary="通过ID检索物品")
def read_item(item_id: int):
    """
    通过物品 ID 检索物品。

    - **item_id**: int - 要检索的物品的唯一标识符。
    """
    return {
        "item_id": item_id,
        "name": "Sample",
        "description": "A sample item",
        "price": 10.0,
    }


@app.post("/users/", tags=["users"], summary="创建新用户", response_model=User)
def create_user(user: User):
    """
    创建一个新的用户记录。

    - **user**: User - 必须提供用户的用户名、全名和电子邮件地址。
    """
    return user


@app.get("/users/{username}", tags=["users"], summary="通过用户名检索用户")
def read_user(username: str):
    """
    通过用户名检索用户信息。

    - **username**: str - 要检索的用户的唯一用户名。
    """
    return {
        "username": username,
        "full_name": "John Doe",
        "email": "johndoe@example.com",
    }


if __name__ == "__main__":
    uvicorn.run(
        f"{os.path.basename(__file__).split('.')[0]}:app",
        host="127.0.0.1",
        port=8000,
        reload=True,
    )

在这个示例中：

• 使用了两个不同的标签：items 和users。使得在自动生成的文档中，物品相关的端点和用户相关的端点各自分组，从而使文档更加有序。
• 每个 API 端点都有一个简洁的摘要，清楚地描述了端点的功能。
• 通过使用 Pydantic 的 BaseModel，定义了输入数据的结构，并且还指定了 response_model 来确保输出数据的一致性。
• 每个端点的 docstring 提供了详细的参数描述和端点的工作原理，使得其他开发者可以更轻松地理解和使用这些 API。

效果