Path Operationの高度な設定

OpenAPI operationId

注意

あなたがOpenAPIの「エキスパート」でなければ、これは必要ないかもしれません。

path operation で operation_id パラメータを利用することで、OpenAPIの operationId を設定できます。

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"}]

path operation関数 の名前をoperationIdとして使用する

APIの関数名を operationId として利用したい場合、すべてのAPIの関数をイテレーションし、各 path operation の operationId を APIRoute.name で上書きすれば可能です。

そうする場合は、すべての path operation を追加した後に行う必要があります。

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)

豆知識

app.openapi() を手動でコールする場合、その前にoperationIdを更新する必要があります。

注意

この方法をとる場合、各 path operation関数 が一意な名前である必要があります。

それらが異なるモジュール (Pythonファイル) にあるとしてもです。

OpenAPIから除外する

生成されるOpenAPIスキーマ (つまり、自動ドキュメント生成の仕組み) から path operation を除外するには、 include_in_schema パラメータを False にします。

from fastapi import FastAPI

app = FastAPI()


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

docstringによる説明の高度な設定

path operation関数 のdocstringからOpenAPIに使用する行を制限することができます。

\f (「書式送り (Form Feed)」のエスケープ文字) を付与することで、FastAPI はOpenAPIに使用される出力をその箇所までに制限します。

ドキュメントには表示されませんが、他のツール (例えばSphinx) では残りの部分を利用できるでしょう。

from typing import Set, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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


@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