2022-07-05

FastAPIにおけるAPIドキュメンテーション

FastAPIによる自動ドキュメンテーション

FastAPIはデフォルトで、自動APIドキュメンテーションのための2つの強力なツール、Swagger UIとReDocに対応しています。これらのツールは、FastAPIがコードから生成したOpenAPI仕様を解釈し、開発者がAPIとのやり取り方法を理解するために使用できるユーザーフレンドリーなインターフェースを提供します。

Swagger UI

Swagger UIは、インタラクティブなAPIドキュメントを生成するための人気のあるツールです。Swagger UIを使用すると、開発者はAPIのさまざまなエンドポイントやHTTPメソッド、パラメータ、リクエストボディ、レスポンスなどの関連情報を簡単に調査できます。

FastAPIアプリケーションでSwagger UIにアクセスするには、実行中のFastAPIサーバーの/docsエンドポイントに移動するだけです。例えば、アプリケーションがローカルでポート8000で実行されている場合、http://localhost:8000/docsにアクセスします。

Swagger UI

Swagger UIは直感的なインターフェースを提供し、開発者はAPIの詳細を表示するだけでなく、インタラクションも行えます。これは「試してみる」ボタンによって実現されます。開発者はこのボタンを使ってブラウザからAPIにリクエストを送信し、リアルタイムでレスポンスを表示することができます。

ReDoc

ReDocは、美しい人間に読みやすいインタラクティブなAPIドキュメントを生成するための別のツールです。Swagger UIがインタラクティブさに焦点を当てているのに対し、ReDocはクリーンで3つのパネルからなるレイアウトによる明確さと読みやすさを重視しています。

ReDocインターフェースにアクセスするには、実行中のFastAPIサーバーの/redocエンドポイントに移動します。例えば、アプリケーションがローカルでポート8000で実行されている場合、http://localhost:8000/redocにアクセスします。

Redoc

ReDocはAPIエンドポイントをよりシンプルで一直線的なビューで表示し、開発者がより簡単にナビゲートできるようにします。エンドポイント、メソッド、パラメータ、およびレスポンスなどの重要な詳細は全て表示されますが、より効率的な方法で表示されます。ただし、Swagger UIとは異なり、ReDocではAPIとの直接的なインタラクションのオプションは提供されません。

APIにメタデータを追加

APIのメタデータは、APIに関するデータそのものです。これにより、APIの機能に関するコンテキストの詳細や説明が提供されます。FastAPIでは、APIのメタデータを簡単に定義できます。このメタデータは生成されたOpenAPIスキーマに含まれるため、自動APIドキュメンテーションで表示されます。

APIメタデータの定義

FastAPIアプリケーションを作成する際に、FastAPIクラスのインスタンスを作成する際に、APIのメタデータを定義することができます。以下に例を示します。

python

from fastapi import FastAPI

app = FastAPI(
    title="My Super API",
    description="This is a very custom API for our organization",
    version="2.5.0",
)

この例では、メタデータとしてAPIのタイトル、説明、およびバージョンが指定されています。この情報は、Swagger UIとReDocの両方のAPIドキュメンテーションのトップに表示されます。

APIルートにメタデータを追加

FastAPIでは、個々のAPIルートにメタデータを追加することもできます。これは、FastAPIのルートデコレータでtagsパラメータを使用することで行います。これにより、関連するルートをドキュメントでグループ化することができます。

以下は例です。

python

@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Item 1"}, {"name": "Item 2"}]

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

この例では、/items/と/users/のルートがそれぞれ"items"と"users"のタグでグループ化されています。生成されたドキュメントでは、これらのタグによってエンドポイントがグループ化され、APIのナビゲーションが容易になります。

APIルートに説明を追加

APIのルートに説明を追加するには、docstringを使用することができます。docstringの最初の行は概要として使用され、それ以降の行は説明として使用されます。

以下は例です。

python

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    """
    Get a specific item by ID.

    - **item_id**: ID of the item to get
    """
    return {"item_id": item_id}

この例では、"Get a specific item by ID."という概要と"- **item_id**: 取得するアイテムのID"という説明が/items/{item_id}のルートのAPIドキュメントに含まれます。

レスポンスモデルのドキュメンテーション

FastAPIでは、レスポンスのデータ構造を定義するためにPydanticモデルを使用します。これらのモデルは、APIエンドポイントの期待される出力を定義し、自動的にAPIドキュメントのためのJSONスキーマ定義を生成します。

レスポンスモデルの基本的な使用方法

ルートに対してレスポンスモデルを指定するには、ルートデコレータのresponse_modelパラメータを使用します。次の例がそのコンセプトを示しています。

python

from fastapi import FastAPI
from pydantic import BaseModel

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

app = FastAPI()

@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: str):
    # implementation omitted
    pass

この例では、response_modelパラメータは/items/{item_id}ルートがItemモデルのインスタンスを返すことを指定しています。FastAPIはこの情報を使用して、レスポンスデータをバリデーションし、JSONにシリアライズし、APIのOpenAPIスキーマに含めます。

レスポンスモデルに説明を追加

レスポンスモデルに説明を追加するには、ルートデコレータのresponsesパラメータを使用します。このパラメータは、HTTPステータスコードをキーとし、説明とレスポンスのモデルを含む辞書を値として受け入れます。

以下は例です。

python

@app.get("/items/{item_id}", responses={200: {"model": Item, "description": "The requested item"}})
async def read_item(item_id: str):
    # implementation omitted
    pass

この例では、responsesパラメータを使用して、"description"が"The requested item"である200ステータスコードのレスポンスにItemモデルを使用することを指定しています。この説明はAPIドキュメントで表示されます。

異なる可能なレスポンスのドキュメンテーション

FastAPIでは、responsesパラメータを使用して異なるステータスコードに対する異なるレスポンスを指定することができます。異なるステータスコードに対して異なるモデルやデータ構造を指定することができます。

以下は例です。

python

@app.get("/items/{item_id}", responses={
    200: {"model": Item, "description": "The requested item"},
    404: {"description": "Item not found"},
    400: {"description": "Invalid request", "content": {"application/json": {"example": {"detail": "Invalid item ID"}}}},
})
async def read_item(item_id: str):
    # implementation omitted
    pass

この例では、responsesパラメータを使用して、異なるステータスコード200、404、および400のレスポンスをドキュメント化しています。400のステータスコードには、例として{"error": "Invalid item_id"}が提供されています。

クエリパラメータとリクエストボディのドキュメンテーション

FastAPIでは、クエリパラメータとリクエストボディは通常、Pythonの型ヒントとPydanticモデルを使用して定義されます。これにより、リクエストで期待されるデータを明確かつ簡潔な方法で指定できます。ただし、包括的なAPIドキュメンテーションを作成するためには、説明、例、および検証制約などの追加情報を追加する必要がある場合もあります。FastAPIは、クエリパラメータとリクエストボディのためにQueryクラスとBodyクラスを提供することで、これを容易にします。

クエリパラメータのドキュメンテーション

クエリパラメータのドキュメントを追加するには、FastAPIのQueryクラスを使用します。このクラスを使用すると、追加のメタデータを持つクエリパラメータを定義できます。

以下は例です。

python

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, description="The query string to filter items", example="item_name")):
    return {"q": q}

この例では、Queryクラスを使用してqクエリパラメータの説明と例を追加しています。Swagger UIやReDocでドキュメントを表示する際に、追加の情報がパラメータと一緒に表示されます。

リクエストボディのドキュメンテーション

リクエストボディのドキュメントを追加するには、FastAPIのBodyクラスを使用します。このクラスを使用すると、追加のメタデータを持つリクエストボディを定義できます。

以下は例です。

python

from fastapi import FastAPI, Body
from pydantic import BaseModel
from typing import Optional

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

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item = Body(..., description="The item to create", example={"name": "item_name", "price": 42.0})):
    return {"item": item}

この例では、Bodyクラスを使用してitemリクエストボディの説明と例を追加しています。APIドキュメントでリクエストボディが表示される際に、追加の情報が表示されます。

Pydanticモデル内のフィールドのドキュメンテーション

Pydanticモデル内の個々のフィールドに対してドキュメントを提供することもできます。これにはPydanticのFieldクラスを使用します。

以下は例です。

python

from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    name: str = Field(..., description="The name of the item", example="item_name")
    description: Optional[str] = Field(None, description="A brief description of the item", example="A sample item")
    price: float = Field(..., description="The price of the item", example=42.0)
    tax: Optional[float] = Field(None, description="The tax on the item", example=3.5)