FastAPI Swagger 文档：路径操作配置与自定义参数优化

最新推荐文章于 2025-05-31 19:57:20 发布

原创最新推荐文章于 2025-05-31 19:57:20 发布 · 1.6k 阅读

33 ·

CC 4.0 BY-SA版权

文章标签：

#fastapi #python

一起学 FastAPI 专栏收录该内容

47 篇文章

订阅专栏

FastAPI Swagger 文档：路径操作配置与自定义参数优化

FastAPI 提供了丰富的路径操作配置选项，通过定制 Swagger 文档的展示，提升 API 的可读性和易用性。本文介绍了如何使用不同的参数，如 tags、summary、description、response_description、deprecated 等，优化 API 路径操作的文档表现。此外，文章还展示了如何通过装饰器和函数的 docstring 提供详细的文档描述，并确保清晰的 API 分组与版本管理。通过这些配置，开发者可以打造更为专业、易于理解的接口文档，增强开发与使用的便捷性。

文章目录

FastAPI Swagger 文档：路径操作配置与自定义参数优化

以下示例中使用的 Python 版本为 Python 3.10.15，FastAPI 版本为 0.115.4。

一 Swagger 文档示例代码

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()


@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    return item

通过在路径操作装饰器中配置参数，优化 Swagger 文档的展示效果与可读性。运行代码文件 chapter23.py 来启动应用：

$ uvicorn chapter23:app --reload

在 SwaggerUI 中可以查看在线文档：http://127.0.0.1:8000/docs。

二配置响应 HTTP 状态码

配置 status_code 状态码，支持 int 数据类型。

@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    return item

可以通过 from starlette import status 导入状态码，FastAPI 中的 fastapi.status 继承自 Starlette，starlette 中定义的 status 状态码，如下：

HTTP_100_CONTINUE = 100
HTTP_101_SWITCHING_PROTOCOLS = 101
HTTP_102_PROCESSING = 102
HTTP_103_EARLY_HINTS = 103
HTTP_200_OK = 200
HTTP_201_CREATED = 201
HTTP_202_ACCEPTED = 202
HTTP_203_NON_AUTHORITATIVE_INFORMATION = 203
HTTP_204_NO_CONTENT = 204
HTTP_205_RESET_CONTENT = 205
HTTP_206_PARTIAL_CONTENT = 206
HTTP_207_MULTI_STATUS = 207
HTTP_208_ALREADY_REPORTED = 208
HTTP_226_IM_USED = 226
HTTP_300_MULTIPLE_CHOICES = 300
HTTP_301_MOVED_PERMANENTLY = 301
HTTP_302_FOUND = 302
HTTP_303_SEE_OTHER = 303
HTTP_304_NOT_MODIFIED = 304
HTTP_305_USE_PROXY = 305
HTTP_306_RESERVED = 306
HTTP_307_TEMPORARY_REDIRECT = 307
HTTP_308_PERMANENT_REDIRECT = 308
HTTP_400_BAD_REQUEST = 400
HTTP_401_UNAUTHORIZED = 401
HTTP_402_PAYMENT_REQUIRED = 402
HTTP_403_FORBIDDEN = 403
HTTP_404_NOT_FOUND = 404
HTTP_405_METHOD_NOT_ALLOWED = 405
HTTP_406_NOT_ACCEPTABLE = 406
HTTP_407_PROXY_AUTHENTICATION_REQUIRED = 407
HTTP_408_REQUEST_TIMEOUT = 408
HTTP_409_CONFLICT = 409
HTTP_410_GONE = 410
HTTP_411_LENGTH_REQUIRED = 411
HTTP_412_PRECONDITION_FAILED = 412
HTTP_413_REQUEST_ENTITY_TOO_LARGE = 413
HTTP_414_REQUEST_URI_TOO_LONG = 414
HTTP_415_UNSUPPORTED_MEDIA_TYPE = 415
HTTP_416_REQUESTED_RANGE_NOT_SATISFIABLE = 416
HTTP_417_EXPECTATION_FAILED = 417
HTTP_418_IM_A_TEAPOT = 418
HTTP_421_MISDIRECTED_REQUEST = 421
HTTP_422_UNPROCESSABLE_ENTITY = 422
HTTP_423_LOCKED = 423
HTTP_424_FAILED_DEPENDENCY = 424
HTTP_425_TOO_EARLY = 425
HTTP_426_UPGRADE_REQUIRED = 426
HTTP_428_PRECONDITION_REQUIRED = 428
HTTP_429_TOO_MANY_REQUESTS = 429
HTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE = 431
HTTP_451_UNAVAILABLE_FOR_LEGAL_REASONS = 451
HTTP_500_INTERNAL_SERVER_ERROR = 500
HTTP_501_NOT_IMPLEMENTED = 501
HTTP_502_BAD_GATEWAY = 502
HTTP_503_SERVICE_UNAVAILABLE = 503
HTTP_504_GATEWAY_TIMEOUT = 504
HTTP_505_HTTP_VERSION_NOT_SUPPORTED = 505
HTTP_506_VARIANT_ALSO_NEGOTIATES = 506
HTTP_507_INSUFFICIENT_STORAGE = 507
HTTP_508_LOOP_DETECTED = 508
HTTP_510_NOT_EXTENDED = 510
HTTP_511_NETWORK_AUTHENTICATION_REQUIRED = 511

三参数 tags

tags 参数用于为路径操作添加标签，它是由 str 元素组成的 list，通常用于接口分组，表示一类接口。

@app.post("/items01/", response_model=Item, tags=["这是功能A接口"])
async def create_item(item: Item):
    return item


@app.get("/items02/", tags=["这是功能A接口"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users03/", tags=["这是用户A接口"])
async def read_users():
    return [{"username": "johndoe"}]

Swagger 文档如图所示：

在这里插入图片描述

四参数 summary 和 description

@app.post(
    "/items03/",
    response_model=Item,
    summary="这是一个items03接口",
    description="这是一个items03接口，它的作用是...",
)
async def create_item(item: Item):
    return item

Swagger 文档如图所示：

在这里插入图片描述

五参数 response_description

@app.post(
    "/items05/",
    response_model=Item,
    summary="这是一个 summary",
    description="这是一个 description",
    response_description="这是一个 response_description",
)
async def create_item(item: Item):
    """
    这是简述：
    - **name**：名称
    - **description**：描述
    - **price**：价格
    - **tax**：税费
    - **tags**：标签
    """
    return item

注：response_description 用于描述响应，description 通常用于描述路径操作。

Swagger 文档如图所示：

在这里插入图片描述

六参数 deprecated

deprecated 参数可将路径操作标记为弃用，无需删除，常用于 API 接口的版本更新。（讲真：一般不用这个。）

@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
    return [{"item_id": "Foo"}]

路径操作装饰器使用 deprecated=True 后 API 会置灰并有 Warning: Deprecated 显示。 Swagger 文档如图所示：

在这里插入图片描述

七函数的 `docstring` 文档字符串

FastAPI 支持在函数的 docstring 中声明路径操作的描述，能够读取并显示其中的 Markdown 内容，但需注意缩进，否则影响Markdown 格式解析。

@app.post("/items04/", response_model=Item, summary="Create an item")
async def create_item(item: Item):
    """
    这是简述：
    - **name**：名称
    - **description**：描述
    - **price**：价格
    - **tax**：税费
    - **tags**：标签
    """
    return item

Swagger 文档如图所示：

在这里插入图片描述

八完整代码示例

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()


@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    return item


@app.post("/items01/", response_model=Item, tags=["这是功能A接口"])
async def create_item(item: Item):
    return item


@app.get("/items02/", tags=["这是功能A接口"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users03/", tags=["这是用户A接口"])
async def read_users():
    return [{"username": "johndoe"}]


@app.post(
    "/items03/",
    response_model=Item,
    summary="这是一个items03接口",
    description="这是一个items03接口，它的作用是...",
)
async def create_item(item: Item):
    return item


@app.post("/items04/", response_model=Item, summary="Create an item")
async def create_item(item: Item):
    """
    这是简述：
    - **name**：名称
    - **description**：描述
    - **price**：价格
    - **tax**：税费
    - **tags**：标签
    """
    return item


@app.post(
    "/items05/",
    response_model=Item,
    summary="这是一个 summary",
    description="这是一个 description",
    response_description="这是一个 response_description",
)
async def create_item(item: Item):
    """
    这是简述：
    - **name**：名称
    - **description**：描述
    - **price**：价格
    - **tax**：税费
    - **tags**：标签
    """
    return item


@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
    return [{"item_id": "Foo"}]