FastAPIはどのように自動ドキュメントを生成しますか?

Question

Accepted Answer

FastAPIは**コードから自動的にインタラクティブなAPIドキュメントを生成**します。あなたのルート、パラメータ、PydanticモデルはOpenAPIスキーマに変換され、追加作業なしに2つの閲覧可能なドキュメントUI（Swagger UIとReDoc）を動作させます。

## 無料でドキュメントが得られる

```python
class Item(BaseModel):
    name: str
    price: float = Field(gt=0, description="Price in USD")

@app.post("/items", tags=["items"], summary="Create an item")
def create_item(item: Item):
    """Create a new item with a name and price."""   # docstring → endpoint description
    return item
```

型付きされたエンドポイントとモデルを書くだけで、FastAPIは完全なドキュメントを生成します。別のドキュメントファイルを書いたり、保守したりする必要はありません。

## 2つの組み込みドキュメントUI

```text
/docs   → Swagger UI — interactive: browse endpoints AND test them in the browser
          (fill in parameters, send requests, see responses live)
/redoc  → ReDoc — a clean, readable reference-style view
/openapi.json → the raw OpenAPI schema (usable to generate client SDKs, etc.)
```

`/docs`にアクセスすると、すべてのエンドポイントを探索でき、必要なパラメータとレスポンス形状を確認でき、ブラウザから**直接実リクエストを送信**できます。これは開発中およびAPI利用者にとって非常に貴重です。

## ドキュメントコンテンツの出所

```text
Route decorators → paths, HTTP methods, tags, summaries
Type hints       → parameter types, required/optional
Pydantic models  → request/response schemas, field constraints & descriptions
Docstrings       → endpoint descriptions
Field(..., description=, example=) → field-level docs and examples
```

すべては、あなたが既に書いているコードから派生しています。ドキュメントは実装と自動的に**同期した状態**を保ちます。

## ドキュメントの充実

```python
app = FastAPI(title="My API", version="1.0", description="...")
@app.get("/x", response_model=Item, responses={404: {"description": "Not found"}})
```

## なぜ重要なのか

自動インタラクティブドキュメントはFastAPIの最も称賛される機能の1つであり、その人気の主な理由です。

ドキュメントはコード（ルート、型ヒント、Pydanticモデル、ドキュメント文字列）から直接生成されるため、常に実装と**同期した状態**を保ちます。これにより、手書きドキュメントが直面する慢性的なドキュメントの陳腐化という問題を解消します。

インタラクティブなSwagger UI（`/docs`）により、開発者とAPI利用者はブラウザ内でエンドポイントを探索して**ライブテスト**でき、開発者体験を劇的に向上させ、統合摩擦を低減します。

生成されたOpenAPIスキーマは、クライアントSDK生成とコントラクトテストも駆動できます。

本質的に無料でプロフェッショナルで正確なインタラクティブAPIドキュメントを取得すること。これは単に型付けされたコードを書くだけで実現でき、生産性と品質の大きな向上をもたらします。これはFastAPIの重要で特徴的な機能です。