FastAPI インタラクティブ API ドキュメント

FastAPI はコード内の型アノテーションに基づいてインタラクティブな API ドキュメントを自動生成し、デフォルトで Swagger UI と ReDoc の2つのインターフェースを提供します。開発者はドキュメント上で直接 API をテストでき、追加のツールは必要ありません。

API ドキュメントにアクセス

FastAPI アプリを実行後、以下のアドレスにアクセスしてドキュメントを確認します：

アドレスドキュメントの種類特徴
http://127.0.0.1:8000/docsSwagger UI対話的にテスト可能です。「Try it out」をクリックするとリクエストを送信できます
http://127.0.0.1:8000/redocReDoc読みやすく、API 定義の閲覧や確認に適しています
http://127.0.0.1:8000/openapi.jsonOpenAPI JSON生の OpenAPI 仕様 JSON。ツールで利用できます

Swagger UI

Swagger UI は直感的なユーザーインターフェースを提供し、ブラウザ上で直接 API をテストできます：

API をテストする手順

  1. テストするルートをクリックして詳細を展開します
  2. クリック"Try it out"ボタン
  3. パラメータの値を入力します
  4. クリック"Execute"ボタンでリクエストを送信します
  5. レスポンス結果を確認します

ReDoc

ReDoc はドキュメントの可読性を重視しており、API 定義の閲覧に適しています：

OpenAPI 仕様

FastAPI はOpenAPI標準を使用して、API を「スキーマ」（Schema）に変換します。アクセスhttp://127.0.0.1:8000/openapi.jsonすると、元の OpenAPI JSON を確認できます：

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/{item_id}": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response"
                    }
                }
            }
        }
    }
}

OpenAPI 仕様の用途：

  • Swagger UI と ReDoc のドキュメントシステムを駆動します
  • さまざまな言語のクライアントコードを自動生成します
  • API テストツール（Postman など）との統合
  • 多数のサードパーティ製ツールやプラットフォームと互換性があります

API ドキュメント情報のカスタマイズ

FastAPI インスタンスを作成する際に、ドキュメントのメタデータをカスタマイズできます：

例

from fastapi import FastAPI

app = FastAPI(
    title=マイ API,                    # API タイトル
    description=これはドキュメントのカスタマイズ機能を示すサンプル API です,  # API 説明
    version="1.0.0",                    # API バージョン
    terms_of_service="http://example.com/terms/",  # 利用規約 URL
    contact={                           # 連絡先情報
        "name": 開発者,
        "url": "http://example.com/contact/",
        "email": "[email protected]",
    },
    license_info={                      # ライセンス情報
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

ルートにドキュメント情報を追加する

デコレータと関数内で各ルートに詳細なドキュメント情報を追加できます：

例

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get(
    "/items/{item_id}",
    summary=商品情報の取得,              # 簡潔な要約
    description=商品 ID に基づいて商品の詳細情報を取得します,  # 詳細な説明
    response_description=商品情報オブジェクト,   # レスポンス説明
    tags=[商品管理],                   # グループ化タグ
)
async def read_item(
    item_id: Annotated[int, Path(ge=1, description=商品ID)],
    q: Annotated[str | None, Query(description=検索キーワード)] = None,
):
    """
商品情報の取得：

- **item_id**: 商品の一意の識別子
- **q**: 任意の検索キーワード
    """
    return {"item_id": item_id, "q": q}

ドキュメントパラメータの説明：

パラメータ場所説明
summaryデコレータルートの簡潔な要約。ルート一覧に表示されます
descriptionデコレータルートの詳細な説明。Markdown 対応
response_descriptionデコレータレスポンスの説明
tagsデコレータルートのグループ化。ドキュメント内でタグごとに分類表示されます
docstring関数本体関数のドキュメント文字列。説明として表示されます

同時に設定されている場合、descriptionつまり関数の docstring もある場合は、description前者が優先されます。docstring は Markdown 形式に対応しており、長い説明の作成に適しています。

tags を使用したグループ化

tagsパラメータを使用すると、関連するルートを1つのグループにまとめ、ドキュメント内でより明確に表示できます：

例

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/", tags=[ユーザー管理])
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]


@app.get("/items/", tags=[商品管理])
async def read_items():
    return [{"name": "Foo"}, {"name": "Bar"}]

Swagger UI では、ルートはタグごとにグループ化されて表示されます。

ドキュメントの無効化

本番環境では、自動ドキュメントを無効にしたい場合があるかもしれません：

例

from fastapi import FastAPI

# ドキュメントを無効化
app = FastAPI(docs_url=None, redoc_url=None)

まとめ

  • FastAPI は Swagger UI と ReDoc の2種類のインタラクティブドキュメントを自動生成します
  • ドキュメントの内容はコード内の型アノテーションに基づいて自動生成され、コードを更新するとドキュメントも自動的に同期されます
  • などのパラメータをtitle、description、tags使用して、ドキュメント情報をカスタマイズできます。
  • 関数の docstring もドキュメントに表示されます
  • 本番環境では、docs_url=Noneドキュメントを無効化できます。
その他の拡張