FastAPIでドキュメントを自動生成する方法

プログラミング

FastAPIによるAPIドキュメントの自動生成

FastAPIは、Pythonの標準的な型ヒントを活用することで、APIのドキュメントを自動的に生成する強力な機能を提供します。これにより、開発者はAPIの仕様を記述する手間を大幅に削減し、より本質的な開発に集中できるようになります。生成されるドキュメントは、Swagger UIとReDocという2つの形式で提供され、それぞれ異なる利便性を提供します。

Swagger UI

Swagger UIは、インタラクティブなAPIドキュメントビューアーです。APIエンドポイント、リクエストパラメータ、レスポンス形式などを視覚的に確認できるだけでなく、実際にAPIを試すための機能も備えています。これにより、APIの利用者は、コードを書くことなくAPIの動作を確認し、理解を深めることができます。FastAPIでは、自動的に /docs エンドポイントにSwagger UIがデプロイされます。

Swagger UIの機能

  • APIエンドポイントのリスト表示: 利用可能なすべてのAPIエンドポイントが一覧表示されます。
  • リクエスト・レスポンスのスキーマ表示: 各エンドポイントが期待するリクエストの形式（クエリパラメータ、パスパラメータ、リクエストボディなど）と、返却するレスポンスの形式（ステータスコード、レスポンスボディの構造など）が明確に表示されます。
  • インタラクティブなAPIテスト: 各エンドポイントに対して、実際にパラメータを入力してAPIを呼び出し、その結果を確認することができます。これは、API開発時のデバッグや、API利用時の動作確認に非常に役立ちます。
  • 認証情報の管理: APIが認証を必要とする場合、Swagger UI上でAPIキーやOAuthトークンなどの認証情報を設定し、APIリクエストに含めることができます。

Swagger UIのカスタマイズ

FastAPIのSwagger UIは、デフォルトで提供されますが、いくつかの方法でカスタマイズすることも可能です。例えば、APIのタイトル、説明、バージョン情報などを FastAPI クラスのインスタンス化時に設定することができます。


from fastapi import FastAPI

app = FastAPI(
    title="My Awesome API",
    description="This is a sample API built with FastAPI",
    version="1.0.0",
)

また、 openapi_url パラメータを使用して、OpenAPI仕様書のURLを変更したり、 docs_url パラメータでSwagger UIのURLを変更することも可能です。


app = FastAPI(docs_url="/api/v1/docs")

ReDoc

ReDocは、もう一つのAPIドキュメント生成ツールです。Swagger UIと比較して、より静的で読みやすいドキュメントを提供することに重点を置いています。ReDocは、APIの概要、エンドポイント、パラメータ、レスポンスなどを、洗練されたデザインのウェブページとして表示します。FastAPIでは、自動的に /redoc エンドポイントにReDocがデプロイされます。

ReDocの利点

  • 読みやすさ: スッキリとしたレイアウトで、APIの全体像や各部分の詳細を把握しやすいです。
  • ナビゲーション: サイドバーなどで、APIのセクション間をスムーズに移動できます。
  • PDFエクスポート: 一部のReDoc実装では、ドキュメントをPDF形式でエクスポートする機能が提供されており、オフラインでの参照や共有に便利です。

ReDocのカスタマイズ

ReDocのカスタマイズも、Swagger UIと同様に FastAPI クラスのインスタンス化時の設定や、 redoc_url パラメータを使用して行うことができます。


app = FastAPI(redoc_url="/api/documentation")

OpenAPI仕様書

FastAPIが生成するSwagger UIとReDocの基盤となっているのが、OpenAPI仕様書です。OpenAPI（旧Swagger）は、RESTful APIの設計と記述のための標準的な仕様であり、JSONまたはYAML形式でAPIの構造を定義します。FastAPIは、Pythonの型ヒントやデコレータから自動的にOpenAPI仕様書を生成し、それを元にSwagger UIやReDocを提供します。このOpenAPI仕様書は、 /openapi.json または /openapi.yaml エンドポイントからアクセスできます。

OpenAPI仕様書の活用

  • APIクライアントコード生成: OpenAPI仕様書から、様々なプログラミング言語（Python, JavaScript, Javaなど）のAPIクライアントコードを自動生成できます。これにより、APIとの連携開発が格段に容易になります。
  • APIゲートウェイとの連携: APIゲートウェイがOpenAPI仕様書を解釈し、ルーティング、認証、レート制限などの機能を提供することができます。
  • ドキュメント生成ツールの基盤: Swagger UIやReDoc以外にも、OpenAPI仕様書を元にした様々なドキュメント生成ツールが存在します。

OpenAPI仕様書への情報追加

FastAPIでは、型ヒントやPydanticモデルを使用することで、APIのパラメータやレスポンスのスキーマ情報を自動的にOpenAPI仕様書に含めることができます。さらに、 openapi_extra パラメータや、各パスオペレーション関数に summary、 description、 tags などの引数を追加することで、ドキュメントに表示される情報をよりリッチにすることができます。


from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(
    item_id: int,
    q: Optional[str] = Query(None, alias="query-param"),
):
    """
    指定されたIDのアイテムを取得します。

    - **item_id**: 取得するアイテムのID
    - **q**: オプショナルなクエリパラメータ
    """
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

上記の例では、docstringを使って item_id と q の説明を追加しています。これにより、Swagger UIやReDocに表示されるドキュメントがより分かりやすくなります。

Pydanticモデルとの連携

FastAPIは、データバリデーションとシリアライゼーションのためにPydanticライブラリを深く統合しています。Pydanticモデルをリクエストボディやレスポンスの型として使用すると、FastAPIは自動的にそのモデルのスキーマを解析し、OpenAPI仕様書に反映させます。これにより、APIのデータ構造が明確になり、ドキュメントの正確性も向上します。


from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_offer: Optional[bool] = None

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
    return item

この例では、 Item というPydanticモデルを定義しています。 create_item エンドポイントでこのモデルをリクエストボディの型として指定することで、FastAPIは自動的に {"name": "...", "price": ..., "is_offer": ...} という構造のJSONリクエストを期待することを認識し、ドキュメントに反映します。また、レスポンスとしても Item モデルを返す場合、その構造がドキュメントに表示されます。

まとめ

FastAPIのドキュメント自動生成機能は、API開発における生産性を飛躍的に向上させます。Swagger UIによるインタラクティブなテスト機能と、ReDocによる読みやすい静的ドキュメントの提供は、開発者とAPI利用者の双方にとって大きなメリットとなります。Pydanticモデルとの連携により、データ構造の定義とドキュメント生成がシームレスに行われ、OpenAPI仕様書はAPIエコシステム全体での相互運用性を高めるための重要な役割を果たします。これらの機能を活用することで、より堅牢で、理解しやすく、保守しやすいAPIを迅速に開発することが可能になります。