Path Operationの設定¶

*path operationデコレータ*を設定するためのパラメータがいくつかあります。

"注意"

これらのパラメータは*path operation関数*ではなく、*path operationデコレータ*に直接渡されることに注意してください。

レスポンスステータスコード¶

*path operation*のレスポンスで使用する（HTTP）status_codeを定義することができます。

404のようにintのコードを直接渡すことができます。

しかし、それぞれの番号コードが何のためのものか覚えていない場合は、statusのショートカット定数を使用することができます:

from typing import Set, Union

from fastapi import FastAPI, status
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, status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    return item

そのステータスコードはレスポンスで使用され、OpenAPIスキーマに追加されます。

"技術詳細"

また、from starlette import statusを使用することもできます。

FastAPI は開発者の利便性を考慮して、fastapi.statusと同じstarlette.statusを提供しています。しかし、これはStarletteから直接提供されています。

タグ¶

tagsパラメータをstrのlist（通常は１つのstr）と一緒に渡すと、*path operation*にタグを追加できます:

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, tags=["items"])
async def create_item(item: Item):
    return item


@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]

これらはOpenAPIスキーマに追加され、自動ドキュメントのインターフェースで使用されます:

概要と説明¶

summaryとdescriptionを追加できます:

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",
    description="Create an item with all the information, name, description, price, tax and a set of unique tags",
)
async def create_item(item: Item):
    return item

docstringを用いた説明¶

説明文は長くて複数行におよぶ傾向があるので、関数docstring内に*path operation*の説明文を宣言できます。すると、FastAPI は説明文を読み込んでくれます。

docstringにMarkdownを記述すれば、正しく解釈されて表示されます。（docstringのインデントを考慮して）

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
    """
    return item

これは対話的ドキュメントで使用されます:

レスポンスの説明¶

response_descriptionパラメータでレスポンスの説明をすることができます。

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",
    response_description="The created 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
    """
    return item

"情報"

respnse_descriptionは具体的にレスポンスを参照し、descriptionは*path operation*全般を参照していることに注意してください。

"確認"

OpenAPIは*path operation*ごとにレスポンスの説明を必要としています。

そのため、それを提供しない場合は、FastAPI が自動的に「成功のレスポンス」を生成します。

非推奨のpath operation¶

*path operation*をdeprecatedとしてマークする必要があるが、それを削除しない場合は、deprecatedパラメータを渡します:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]


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

対話的ドキュメントでは非推奨と明記されます:

*path operations*が非推奨である場合とそうでない場合でどのように見えるかを確認してください:

まとめ¶

*path operationデコレータ*にパラメータを渡すことで、*path operations*のメタデータを簡単に設定・追加することができます。