APIリファレンスの自動生成

「APIリファレンス」ナビゲーションに表示されているAPI仕様書（各エンドポイントのMarkdown）は、 api/ (FastAPI) のコードから自動生成されています。手で編集しないでください。

仕組み

api/ のルーター・Pydanticスキーマ
       │  (FastAPIが自動でOpenAPIスキーマを構築)
       ▼
api/scripts/export_openapi.py ── docs/openapi/happa-api.json を出力
       │  (docusaurus-plugin-openapi-docs)
       ▼
npm run gen-api-docs ── docs/docs/api/*.mdx を生成

生成されたMarkdown（docs/docs/api/）と docs/openapi/happa-api.json はリポジトリにコミットされています。 api/ にエンドポイントの追加・変更を行ったら、以下の手順で再生成してPRに含めてください。

再生成手順

# 1. リポジトリルートで、APIのOpenAPIスキーマをJSONに書き出す
cd api
pip install -r requirements.txt   # 未インストールの場合
cd ..
python -m api.scripts.export_openapi

# 2. docs/ 側でMarkdownを生成
cd docs
npm run gen-api-docs

gen-api-docs は既存の docs/docs/api/ を上書きします。差分を確認してからコミットしてください。

設定箇所

• api/scripts/export_openapi.py: FastAPIアプリをDBに接続せず読み込み、app.openapi() の結果をJSONに書き出すスクリプト
• docs/docusaurus.config.ts: docusaurus-plugin-openapi-docs の設定（入力: docs/openapi/happa-api.json、出力: docs/docs/api/）
• docs/sidebars.ts: 生成された docs/docs/api/sidebar.ts を apiSidebar として読み込み