🗺️ FastAPI — 設計書と TDD

テクノロジ系／ L19 design-tdd — 設計書と TDD

🗺️ FastAPI — 設計書と TDD

API 設計書とは何か + テスト駆動開発 (TDD) で実装を進める

作るもの

イベント参加登録 API

社内勉強会に「参加申込」できる Web API

参加者が申し込む        → POST /registrations
申込一覧を見る          → GET  /registrations
申込をキャンセルする    → DELETE /registrations/{id}
管理者だけが見られる    → X-API-Key 認証

ゴールマップ — どの STEP で「何を」書くのか

STEP	テーマ	触るファイル	やること
1	設計書を読む	`main.py` (アプリ実装)	最小アプリを動かす
2	設計書 → テスト	`test_main.py` のみ (テストコード)	仕様をテストコードに翻訳 (Red)
3	Green にする	`main.py` のみ (アプリ実装)	アプリ実装を書いて STEP2 のテストを通す
4	テスト先行 TDD	`test_main.py` → `main.py`	新機能のテストを先に書く → アプリ実装で通す
5	認証を追加	`test_main.py` → `main.py`	認証テストを書く → Depends でアプリ実装

> 用語: 本資料では 「テストコード」 = test_main.py の内容 / 「アプリ実装」 = main.py の内容 と書き分けます。

> 「実装」と書かれていたら アプリ実装 (main.py) のこと。テストコードを書くことは「テストを書く」と表現します。

starter / answer の使い方

サンプルコード/
├── step1/
│   ├── starter/main.py   ← ここから書き始める
│   └── answer/main.py    ← 完成形 (詰まったら参考に)
├── step2/ ...
└── 完成品/main.py

各 STEP の starter は前 STEP の answer と同じ内容。

「STEP2 の answer」と「STEP3 の starter」は同一。

📋 API 設計書とは何か

「作る前に決める」ための地図

コードを書く前に、以下を決めておく文書:

何ができるか — 機能の一覧
どう呼ぶか — URL / メソッド / パラメータ
何が返るか — レスポンスの形
どう失敗するか — エラーの種類と意味

> 地図なしで山を登ると迷子になる。API も同じ。

設計書がないと何が起きるか

❌ 「GET を返すと思っていたら POST だった」

❌ 「404 が返ってきたけどなぜか分からない」

❌ 「フロントとバックで項目名が違う」

❌ 「納品直前に仕様変更が分かった」

→ 全部「先に決めていなかった」から起きる

設計書があると何が変わるか

✅ フロントとバックが同じ設計書を見て並行開発できる

✅ 「仕様通りに動いているか」をテストで確認できる

✅ 後から参加した人が全体像を即座に把握できる

✅ 「なぜこうなっているか」の理由が残る

設計書の5つの構成要素

1. 概要      — このAPIで何ができるか (1段落)
2. データ設計 — 何を保存するか (テーブル形式)
3. エンドポイント一覧 — どんな操作があるか
4. 詳細仕様   — 各エンドポイントの IN/OUT
5. エラー仕様 — 異常時にどう返すか

例: エンドポイント一覧の書き方

メソッド	パス	何をする	認証
GET	/registrations	申込一覧を取得	必要
POST	/registrations	新規申込	不要
GET	/registrations/{id}	1件取得	必要
DELETE	/registrations/{id}	申込をキャンセル	必要

→ これだけで「どんな API か」が一目でわかる

例: リクエスト/レスポンスの書き方

POST /registrations リクエスト:

{
  "name": "山田太郎",
  "email": "yamada@example.com",
  "event": "FastAPI勉強会"
}

レスポンス (201 Created):

{
  "id": 1,
  "name": "山田太郎",
  "status": "registered",
  "created_at": "2026-06-09T10:00:00"
}

例: エラー仕様の書き方

状況	ステータス	返すもの
必須項目が無い	422	バリデーションエラー
存在しない ID	404	`{"detail": "registration not found"}`
認証キーが間違い	401	`{"detail": "invalid api key"}`

→ エラーの仕様を先に決めると、フロントの「エラー処理」も先に書ける

OpenAPI / Swagger との関係

FastAPI は起動すると 自動的に OpenAPI 形式の設計書を生成する:

http://localhost:8000/docs   ← Swagger UI (ブラウザで操作できる設計書)
http://localhost:8000/openapi.json  ← 機械が読める設計書 (JSON)

つまり、FastAPI のコードを書くと設計書が自動で生成される。

→ コードと設計書が常に一致している状態になる。

Swagger UI でできること

エンドポイント一覧を確認する
リクエスト / レスポンスのスキーマを確認する
ブラウザから実際にリクエストを送る (Try it out)
チームメンバーに「ここを見て」と URL を渡す

→ curl コマンドを書かなくても動作確認ができる

設計書の書き方: 実務の流れ

1. 要件をヒアリング / 整理する
   「何ができれば嬉しいか」を箇条書きで集める

2. データモデルを決める
   「何を保存するか」= テーブルの列と型を書く

3. エンドポイントを洗い出す
   CRUD の何が必要か = 一覧 / 取得 / 作成 / 更新 / 削除

4. IN/OUT の形を決める
   リクエストとレスポンスの JSON の形を書く

5. エラーを洗い出す
   「失敗するとしたら何か」= 404 / 401 / 422 の条件

設計書をどう読むか (読み方の手引き)

新人が設計書を初めて読むとき、「上から全部読もうとして 30 分溶かす」のは典型ミス。

目的を決めて読む のが鉄則。

この後やること	設計書のどこを読めばいい?
最小実装を動かす (STEP 1)	§4 エンドポイント一覧
テストを書く (STEP 2)	§5 詳細仕様 + §8 受入条件
認証を実装する (STEP 5)	§6 認証の決まり
エラー処理を書く (各 STEP)	§7 エラーレスポンスの統一

→ 設計書は「仕様の引き出し」。必要な時に必要な節を引く。

配布資料の設計書を読む

配布資料/設計書/API設計書_イベント参加登録.pdf を開いてください。

まず 5 分で全体を眺める。 以下を確認:

[ ] エンドポイントは何個ある? (§4)
[ ] 認証が必要なのはどの操作? (§4 / §6)
[ ] POST のレスポンスに含まれるフィールドは? (§5.1)
[ ] 404 はどんな時に返る? (§7)

→ 答えられたら STEP 1 へ進む。答えられない項目があれば該当節をもう一度。

🔴🟢 TDD — テスト駆動開発

TDD とは

Test-Driven Development — テストコードを先に書いてからアプリ実装を書く開発手法

> 本資料では「アプリ実装 = main.py のコード」「テストコード = test_main.py のコード」と呼び分けます。

Red      → テストコードを書く → FAIL する (当然: main.py にアプリ実装がないから)
Green    → main.py にアプリ実装を書く → PASS する
Refactor → コードを整理する (テストは PASS のまま)

このサイクルを小さく回す。

なぜテストを先に書くのか

テストコードは「設計書を機械が読める形にしたもの」

アプリ実装を始める前に「何を作るか」が明確になる
テストが通れば「仕様通りに動いている」と言える
リファクタリングしても壊れていないと確認できる
「動く」と「仕様通りに動く」は違う

テスト先行なしの開発で起きること

main.py を書く → ブラウザで手動確認 → 「なんか動いた」
    ↓
数週間後: 「あれ、あの機能壊れてる」
    ↓
「いつ壊れたのか分からない」「何を変えたら直るのか分からない」

→ テストがあれば「壊れた瞬間」が分かる

FastAPI でのテスト: TestClient

from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_post_registration():
    res = client.post("/registrations", json={
        "name": "山田太郎",
        "email": "yamada@example.com",
        "event": "FastAPI勉強会",
    })
    assert res.status_code == 201

→ サーバーを起動しなくても API をテストできる

なぜ TestClient はサーバ起動なしで動くのか

観点	通常のリクエスト	TestClient
経路	ブラウザ → ネットワーク → uvicorn → FastAPI app	テストプロセス内で直接 FastAPI app を呼ぶ
ポート	8000 を listen する必要あり	ポート不要
速度	TCP / HTTP オーバーヘッドあり	ms 単位で連続実行可
中身	別プロセス	同一 Python プロセス (in-process)

→ TestClient(app) は app を ASGI アプリとして直接呼ぶ薄いラッパー。

本物の HTTP は流れないが、同じ Pydantic バリデーション・同じ依存解決・同じレスポンスが返る。

だから client.post(...) の戻り値はブラウザで叩いた時と同じ Response。

pytest 実行の全体フロー

!h:680

→ ユーザーが手を動かすのは ① 〜 ③ の 3 ステップ。

中の細かい流れ (from main import app や client.post(...)) は テストコードが勝手にやる。

テストの書き方: 設計書をコードに翻訳する

設計書:

> POST /registrations → 201 Created

テスト:

def test_post_registration_returns_201():
    res = client.post("/registrations", json={...})
    assert res.status_code == 201

テストの書き方: エラー仕様もテストにする

設計書:

> 必須項目が無い → 422

テスト:

def test_post_missing_name_returns_422():
    res = client.post("/registrations", json={
        "email": "yamada@example.com",
        "event": "FastAPI勉強会",
        # name がない
    })
    assert res.status_code == 422

pytest の実行方法

# テストを実行する
python3 -m pytest test_main.py -v

# -v = 詳細表示 (どのテストが PASS/FAIL か)

PASS:

test_main.py::test_post_registration_returns_201 PASSED

FAIL:

test_main.py::test_post_registration_returns_201 FAILED

Red → Green の体験 (STEP2 → STEP3)

STEP2 でやること:

step2/starter/main.py はそのまま (アプリ実装を足さない)
step2/starter/test_main.py に設計書の仕様を書く
pytest を実行 → FAIL (Red) を確認

STEP3 でやること:

step3/starter/main.py にアプリ実装を追加する
pytest を実行 → PASS (Green) を確認

🛠️ STEP 1: 設計書を読む

最小 FastAPI を動かす

STEP 1 の流れ

!h:680

STEP 1 でやること

> 触るファイル: step1/starter/main.py (アプリ実装)

> テストファイルは触りません。まずアプリが起動することを確認する STEP。

配布資料/設計書/API設計書_イベント参加登録.pdf を読む (5分)
step1/starter/main.py を開く
FastAPI アプリを作って GET /registrations を追加する
uvicorn main:app --reload で起動
http://localhost:8000/docs で Swagger UI を確認

最小コード (ヒント)

from fastapi import FastAPI

app = FastAPI(title="イベント参加登録 API")

@app.get("/registrations")
def list_registrations():
    return []

→ 空リストを返すだけで OK。STEP2 以降で実装を足す。

STEP 1 完成イメージ

http://localhost:8000/docs を開くと:

/registrations エンドポイントが表示されている
"Try it out" → "Execute" でレスポンス [] が返る

🔴 STEP 2: 設計書 → テスト (Red)

テストを書いて FAIL させる

STEP 2 の流れ

!h:680

STEP 2 でやること

> 触るファイル: step2/starter/test_main.py のみ (テストコード)

> main.py は STEP1 の状態のまま。アプリ実装を足さないからテストが落ちる ̶ それが Red の正解。

step2/starter/test_main.py を開いて、以下のテストを書く:

POST /registrations で 201 が返ること (設計書 §5.1)
POST のレスポンスに id / status / created_at が含まれること (§5.1)
name を省略すると 422 が返ること (§5.1 エラー)
GET /registrations がリストを返すこと (§5.2)
GET /registrations で X-API-Key 無しなら 401 が返ること (§6 認証 / §8 受入条件)

→ 設計書の §5 詳細仕様 / §6 認証 / §8 受入条件 から導いている。

> 5 つ目は STEP 5 でアプリ実装を書く「認証」の 仕様だけ先に書いておく パターン。

> テストコードは書けるがアプリ実装が無いので Red になる ̶ これが TDD の自然な進め方。

テストの書き方 (テンプレート)

from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_post_registration_returns_201():
    res = client.post("/registrations", json={
        "name": "山田太郎",
        "email": "yamada@example.com",
        "event": "FastAPI勉強会",
    })
    assert res.status_code == 201

実行して Red を確認

cd step2/starter
python3 -m pytest test_main.py -v

予想される結果:

FAILED test_main.py::test_post_registration_returns_201

→ FAIL して当然。アプリ実装がないのだから。これが Red。

STEP 2 でハマりやすいポイント

症状	原因	対処
`ModuleNotFoundError: No module named 'main'`	`step2/starter/` 以外で実行している	`cd step2/starter` してから `pytest`
`ModuleNotFoundError: No module named 'fastapi'`	venv が有効化されていない	プロンプトに `(.venv)` が付いているか確認
すべて PASS してしまう	テスト関数名が `test_` で始まっていない	pytest は `test_` で始まる関数のみ自動検出
GET テストだけ PASS する	STEP1 で `GET /registrations` を空配列で返している	想定内 (POST 系 4 件は FAIL する)

> どこから pytest を実行する? → 必ず step2/starter/ 内。

> test_main.py の from main import app は 「同じディレクトリの main.py を読む」 意味。

🟢 STEP 3: テストを通す (Green)

アプリ実装を書いて PASS させる

STEP 3 の流れ

!h:680

STEP 3 でやること

> 触るファイル: step3/starter/main.py のみ (アプリ実装)

> test_main.py は STEP2 で書いたものが既に step3/starter/ にコピーされている。触らない。

step3/starter/main.py にアプリ実装を追加して、 STEP2 のテストを全て PASS させる。

追加する要素:

RegistrationCreate Pydantic モデル (name / email / event)
POST /registrations → 201 + フィールド全部返す
インメモリリスト (_registrations) でデータを保持

Pydantic でリクエストボディを定義する

from pydantic import BaseModel

class RegistrationCreate(BaseModel):
    name: str
    email: str
    event: str

→ FastAPI が自動的にバリデーション。name が無ければ 422 を返す。

POST エンドポイントの実装

_registrations = []
_next_id = 1

@app.post("/registrations", status_code=201)
def create_registration(body: RegistrationCreate):
    global _next_id
    record = {
        "id": _next_id,
        "name": body.name,
        "email": body.email,
        "event": body.event,
        "status": "registered",
        "created_at": datetime.now().isoformat(timespec="seconds"),
    }
    _registrations.append(record)
    _next_id += 1
    return record

実行して Green を確認

cd step3/answer
python3 -m pytest test_main.py -v

予想される結果:

test_main.py::test_post_registration_returns_201             PASSED
test_main.py::test_post_registration_returns_fields          PASSED
test_main.py::test_post_registration_missing_name_returns_422 PASSED
test_main.py::test_get_registrations_is_list                 PASSED
test_main.py::test_delete_registration                       PASSED
test_main.py::test_get_registration_not_found                PASSED

→ 全て PASS = Green 🟢 (DELETE / 404 も含めて 6 件)

🔄 STEP 4: テスト先行 TDD

新機能をテストから書く

STEP 4 の流れ

!h:680

STEP 4 でやること

> 触るファイル: step4/starter/test_main.py → step4/starter/main.py (テスト先行 → アプリ実装)

> ここで初めて「1 STEP 内でテストコードとアプリ実装の両方を触る」。これが TDD の本番リズム。

新機能「絞り込み」をテストから書く:

GET /registrations?event=FastAPI勉強会 → そのイベントだけ返す
GET /registrations?status=registered → 有効申込だけ返す

手順:

test_main.py に新機能のテストを書く
pytest → FAIL (Red)
main.py にクエリパラメータを追加
pytest → PASS (Green)

テストを先に書く (STEP4 の起点)

def test_filter_by_event():
    # 2種類のイベントを登録
    client.post("/registrations", json={
        "name": "Aさん", "email": "a@example.com", "event": "FastAPI勉強会",
    })
    client.post("/registrations", json={
        "name": "Bさん", "email": "b@example.com", "event": "TDD入門",
    })

    # FastAPI勉強会だけ絞り込む
    res = client.get("/registrations", params={"event": "FastAPI勉強会"})
    assert res.status_code == 200
    assert all(item["event"] == "FastAPI勉強会" for item in res.json())

クエリパラメータの実装

from typing import Optional

@app.get("/registrations")
def list_registrations(
    event: Optional[str] = None,
    status: Optional[str] = None,
):
    result = _registrations
    if event is not None:
        result = [r for r in result if r["event"] == event]
    if status is not None:
        result = [r for r in result if r["status"] == status]
    return result

TDD サイクルのまとめ

① テストを書く   → "filter_by_event をテスト"
② pytest 実行   → FAIL (Red) ✅ 当然
③ アプリ実装を書く → "クエリパラメータを追加"
④ pytest 実行   → PASS (Green) ✅ 完成
⑤ 整理する      → Refactor (今回は不要)
⑥ 次の機能へ    → ① に戻る

🔐 STEP 5: APIKey 認証

管理者操作を守る

STEP 5 の流れ

!h:680

STEP 5 でやること

> 触るファイル: step5/starter/test_main.py → step5/starter/main.py (テスト先行 → アプリ実装)

> 認証テスト 5 種類を先に書いて Red → Depends でアプリ実装して Green。 STEP4 と同じリズム。

設計書 §6「認証の決まり」のアプリ実装を書く:

X-API-Key: secret-key-123 ヘッダがあれば通す
なければ 401 を返す
POST だけは認証不要 (誰でも申し込める)

`Depends` で認証を共通化する

from fastapi import Depends, Header, HTTPException

_VALID_API_KEY = "secret-key-123"

def require_api_key(x_api_key: str = Header(default=None)):
    if x_api_key != _VALID_API_KEY:
        raise HTTPException(status_code=401, detail="invalid api key")

→ この関数を一度書けば、複数のエンドポイントで使い回せる。

認証が必要なエンドポイントに適用する

@app.get("/registrations", dependencies=[Depends(require_api_key)])
def list_registrations(...):
    ...

@app.get("/registrations/{reg_id}", dependencies=[Depends(require_api_key)])
def get_registration(reg_id: int):
    ...

@app.delete("/registrations/{reg_id}", ..., dependencies=[Depends(require_api_key)])
def cancel_registration(reg_id: int):
    ...

→ POST は dependencies を付けない → 認証不要。

テストで認証を確認する

HEADERS = {"X-API-Key": "secret-key-123"}

def test_get_list_without_key_returns_401():
    res = client.get("/registrations")  # キーなし
    assert res.status_code == 401

def test_get_list_with_valid_key():
    res = client.get("/registrations", headers=HEADERS)
    assert res.status_code == 200

`X-API-Key` の仕組み

クライアント                    FastAPI サーバー
    |                               |
    |  GET /registrations           |
    |  X-API-Key: secret-key-123   |
    |------------------------------>|
    |                               |  require_api_key() で検証
    |  200 OK                       |
    |<------------------------------|

    |  GET /registrations (キーなし) |
    |------------------------------>|
    |  401 Unauthorized             |
    |<------------------------------|

STEP 5 動作確認

# キーなし → 401
curl http://localhost:8000/registrations
# → {"detail": "invalid api key"}

# 正しいキー → 200
curl http://localhost:8000/registrations \
  -H "X-API-Key: secret-key-123"

# 申込は認証不要
curl -X POST http://localhost:8000/registrations \
  -H "Content-Type: application/json" \
  -d '{"name":"山田","email":"a@b.com","event":"勉強会"}'

✅ 完成形チェック

実装済みエンドポイント確認

エンドポイント	認証	テスト
POST /registrations	なし	✅
GET /registrations	あり	✅
GET /registrations/{id}	あり	✅
DELETE /registrations/{id}	あり	✅
クエリ絞り込み (event/status)	—	✅
401 (認証エラー)	—	✅
404 (未存在)	—	✅

全テスト一括実行

# step5/answer に移動して 9 件のテストを実行する
cd 配布資料/サンプルコード/step5/answer
python3 -m pytest test_main.py -v

予想される結果: 9 件すべて PASSED (認証 5 件 + 通常操作 4 件)

→ 全て PASS すれば完成 🎉

> 完成品/main.py は step5/answer/main.py と同じ内容。

> 「最終的にこういうコードになる」という参照用なのでテストは持たない。

チャレンジ題

余裕があれば:

メールアドレス検証: Pydantic の EmailStr を使って email フォーマットを検証する

   from pydantic import EmailStr
   class RegistrationCreate(BaseModel):
       email: EmailStr  # 不正なメールアドレスを弾く

同じメールアドレスで二重申込を禁止: POST 時に email を検索して 409 Conflict を返す

ページネーション: GET /registrations?limit=10&offset=0 を追加する

FAQ

Q: インメモリに保存しているので再起動すると消える

A: そうです。次のステップとして SQLite (sqlite3) や JSON ファイルへの永続化があります。

Q: _VALID_API_KEY をコードに直書きしていいの?

A: 学習用なので直書きしています。本番では os.environ["API_KEY"] で環境変数から読みます。

Q: Optional[str] は何?

A: パラメータが省略可能 (= 指定しなくてもよい) であることを示します。= None とセットで使います。

振り返り

今回学んだこと:

API 設計書とは「作る前に何を作るか決める文書」
設計書 → テスト → 実装 の順で作ると仕様ブレが起きない
TestClient を使えばサーバー起動なしに API をテストできる
TDD (Red → Green → Refactor) でテストを先に書く意味
Depends で認証などの共通処理を複数エンドポイントに適用できる

次のステップ

データ永続化: インメモリ → SQLite (再起動してもデータが残る)
型バリデーション強化: EmailStr / 最大文字数 / 正規表現
OpenAPI YAML 出力: GET /openapi.json の内容を保存して他のツールで使う
環境変数での設定管理: python-dotenv / pydantic-settings

お疲れ様でした！

設計書 → テスト → 実装のサイクルを体験できました。

> 「設計書はコードより先に書く。テストは実装より先に書く。」

力試ししたい方はクイズ形式の演習（任意）もあります。読むだけでも十分です。

🗺️ FastAPI — 設計書と TDD