FastAPI教程 路徑操作的高級(jí)配置

OpenAPI 的 operationId

Warning

如果你并非 OpenAPI 的「專家」，你可能不需要這部分內(nèi)容。

你可以在路徑操作中通過(guò)參數(shù) operation_id 設(shè)置要使用的 OpenAPI operationId。

務(wù)必確保每個(gè)操作路徑的 operation_id 都是唯一的。

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/", operation_id="some_specific_id_you_define")
async def read_items():
    return [{"item_id": "Foo"}]

使用 路徑操作函數(shù) 的函數(shù)名作為 operationId

如果你想用你的 API 的函數(shù)名作為 operationId 的名字，你可以遍歷一遍 API 的函數(shù)名，然后使用他們的 APIRoute.name 重寫(xiě)每個(gè) 路徑操作 的 operation_id。

你應(yīng)該在添加了所有 路徑操作 之后執(zhí)行此操作。

from fastapi import FastAPI
from fastapi.routing import APIRoute

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"item_id": "Foo"}]


def use_route_names_as_operation_ids(app: FastAPI) -> None:
    """
    Simplify operation IDs so that generated API clients have simpler function
    names.

    Should be called only after all routes have been added.
    """
    for route in app.routes:
        if isinstance(route, APIRoute):
            route.operation_id = route.name  # in this case, 'read_items'


use_route_names_as_operation_ids(app)

Tip

如果你手動(dòng)調(diào)用 app.openapi()，你應(yīng)該在此之前更新 operationId。

Warning

如果你這樣做，務(wù)必確保你的每個(gè) 路徑操作函數(shù) 的名字唯一。

即使它們?cè)诓煌哪K中（Python 文件）。

從 OpenAPI 中排除

使用參數(shù) include_in_schema 并將其設(shè)置為 False ，來(lái)從生成的 OpenAPI 方案中排除一個(gè) 路徑操作（這樣一來(lái)，就從自動(dòng)化文檔系統(tǒng)中排除掉了）。

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/", include_in_schema=False)
async def read_items():
    return [{"item_id": "Foo"}]

docstring 的高級(jí)描述

你可以限制 路徑操作函數(shù) 的 docstring 中用于 OpenAPI 的行數(shù)。

添加一個(gè) \f （一個(gè)「換頁(yè)」的轉(zhuǎn)義字符）可以使 FastAPI 在那一位置截?cái)嘤糜?OpenAPI 的輸出。

剩余部分不會(huì)出現(xiàn)在文檔中，但是其他工具（比如 Sphinx）可以使用剩余部分。

from typing import Optional, Set

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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


@app.post("/items/", response_model=Item, summary="Create an item")
async def create_item(item: Item):
    """
    Create an item with all the information:

    - **name**: each item must have a name
    - **description**: a long description
    - **price**: required
    - **tax**: if the item doesn't have tax, you can omit this
    - **tags**: a set of unique tag strings for this item
    \f
    :param item: User input.
    """
    return item