PART 04 — API設計書
エンドポイント・リクエスト/レスポンス・エラー定義

■ エンドポイント一覧

No. | HTTPメソッド | パス                        | 処理概要         | 認証
----|-------------|----------------------------|-----------------|------
001 | GET         | /api/v1/users              | ユーザー一覧取得  | JWT
002 | GET         | /api/v1/users/{userId}     | ユーザー詳細取得  | JWT
003 | POST        | /api/v1/users              | ユーザー新規登録  | JWT（ADMIN）
004 | PUT         | /api/v1/users/{userId}     | ユーザー情報更新  | JWT（本人 or ADMIN）
005 | DELETE      | /api/v1/users/{userId}     | ユーザー論理削除  | JWT（ADMIN）
006 | POST        | /api/v1/auth/login         | ログイン         | なし（公開）
007 | POST        | /api/v1/auth/refresh       | トークン更新     | Refresh Token

■ パスパラメータ: なし

■ クエリパラメータ: なし

■ リクエストボディ（application/json）
{
  "loginId":    "string  必須  4〜50文字 英数字アンダースコアのみ",
  "email":      "string  必須  RFC5321準拠 最大255文字",
  "password":   "string  必須  8〜72文字 英大小数記号を各1文字以上含む",
  "lastName":   "string  必須  最大50文字",
  "firstName":  "string  必須  最大50文字",
  "roleCode":   "string  必須  ADMIN / USER / READONLY のいずれか"
}

■ リクエスト例
POST /api/v1/users
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "loginId": "acropolis",
  "email": "acropolis@example.com",
  "password": "P@ssw0rd!",
  "lastName": "山田",
  "firstName": "太郎",
  "roleCode": "USER"
}

■ 成功時（201 Created）
{
  "userId": 12345,
  "loginId": "acropolis",
  "email": "acropolis@example.com",
  "lastName": "山田",
  "firstName": "太郎",
  "roleCode": "USER",
  "createdAt": "2026-06-18T12:00:00+09:00",
  "updatedAt": "2026-06-18T12:00:00+09:00"
}

■ HTTPステータスコード一覧
200 OK          — 取得・更新成功
201 Created     — 新規作成成功
204 No Content  — 削除成功
400 Bad Request — バリデーションエラー
401 Unauthorized— 認証エラー（トークン未提供・期限切れ）
403 Forbidden   — 認可エラー（権限不足）
404 Not Found   — リソースなし
409 Conflict    — 重複エラー（loginId が既存）
500 Internal    — サーバー内部エラー

"""
FastAPI / Spring Boot などの /openapi.json からエンドポイント一覧を取得し
Markdown テーブルとして出力する
pip install requests
"""
import json, requests

OPENAPI_URL = "http://localhost:8080/openapi.json"  # 環境に合わせて変更

def fetch_openapi(url: str) -> dict:
    resp = requests.get(url, timeout=10)
    resp.raise_for_status()
    return resp.json()

def extract_endpoints(spec: dict) -> list[dict]:
    rows = []
    for path, methods in spec.get("paths", {}).items():
        for method, op in methods.items():
            if method in ("get", "post", "put", "patch", "delete"):
                security = op.get("security", [])
                auth = "なし" if not security else list(security[0].keys())[0] if security else "不明"
                rows.append({
                    "method": method.upper(),
                    "path": path,
                    "summary": op.get("summary", "—"),
                    "tags": ", ".join(op.get("tags", [])),
                    "auth": auth,
                })
    return rows

def to_markdown(rows: list[dict]) -> str:
    header = "| Method | Path | Summary | Tags | Auth |"
    sep    = "|--------|------|---------|------|------|"
    lines  = [header, sep]
    for r in rows:
        lines.append(f"| {r['method']} | `{r['path']}` | {r['summary']} | {r['tags']} | {r['auth']} |")
    return "
".join(lines)

try:
    spec = fetch_openapi(OPENAPI_URL)
    rows = extract_endpoints(spec)
    print(f"# API エンドポイント一覧 ({len(rows)} 件)")
    print(to_markdown(rows))
    # JSON ファイルにも保存
    with open("api_spec_extracted.json", "w", encoding="utf-8") as f:
        json.dump(rows, f, ensure_ascii=False, indent=2)
    print("\n✅ api_spec_extracted.json に保存しました")
except Exception as e:
    print(f"❌ 取得失敗: {e}")