3. API・OpenAPI | 工程別ドキュメント運用ガイド

主な読者: SEPG

経営層投資対効果とリスク低減の判断材料。全文読む必要はなく、KPIとBefore/Afterで十分。

PM合意・スコープ・未決の管理。正本が1か所なら炎上の早期検知と説明責任が楽になる。
この章 IF変更の影響見積

SE構造・IF・例外の設計品質。MD+Mermaid+OpenAPIでレビューとAI支援の精度が上がる。
この章契約の正本

PG実装の迷いが減る。AGENTS.md・型生成・PRテンプレで「聞き直し」工数が減る。
この章型自動生成

OpenAPI：正本は分割YAML、Swaggerは窓

サンプル：Swagger UI（bundle後の表示イメージ）

API Docs — orders (OpenAPI 3.1)

POST /api/v1/orders — 受注登録

requestBody

OrderCreate

201

OrderResponse

400

ErrorResponse (共通)

分割サンプル（paths/orders.yaml）

post:
  summary: 受注登録
  operationId: createOrder
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '../components/schemas/OrderCreate.yaml'
  responses:
    '201':
      description: 作成成功
      content:
        application/json:
          schema:
            $ref: '../components/schemas/OrderResponse.yaml'
    '400':
      $ref: '../components/responses/BadRequest.yaml'

立場別メリット

OpenAPI分割運用の立場別メリット
SE	IF変更の影響範囲が明確。レビュー単位が小さくなる（分割のため）
PG	Orval等で型・クライアント自動生成。「口頭仕様」が消える
PM	外部連携の変更を見積もりやすい

巨大1ファイルは早めに分割。SmartHR事例では18k行超で編集不能に近づいてから分割しています。

この工程で使う AI（API・OpenAPI）

API — 契約の正本と整合
役割	ツール例	優れている点	典型用途
スキーマ編集	Claude Code	分割 YAML の多ファイル編集	`paths/*.yaml` · components 追加
破壊的変更検出	CI + openapi-diff	決定的チェック（ゲート Tier 1）	PR で schema 差分ブロック
型生成前提整備	Orval 等 + LLM	手書き DTO を増やさない	bundle 後の型・クライアント同期
Issue 連携	Linear MCP 等	チケット文脈をエージェントへ Just-in-Time 供給	IF 変更の影響見積メモ

成果物サンプル一覧

実際のプロジェクトではファイル名・パスをテンプレに合わせてください。以下は掲載可能な具体イメージ（HTML/CSS埋め込み）です。

openapi/root.yaml

OpenAPI 分割構成

openapi/ ├── root.yaml ├── paths/ │ ├── orders.yaml ← POST /orders, DELETE /orders/{id} │ └── inventory.yaml └── components/ ├── schemas/OrderCreate.yaml └── responses/BadRequest.yaml

openapi/paths/orders.yaml

パス定義

orders.yaml

1post:

2 summary: 受注登録

3 operationId: createOrder

4 requestBody:

5 $ref: '../components/schemas/OrderCreate.yaml'

docs/api/index.html

Swagger UI（表示用）

POST /api/v1/orders 受注登録

DELETE /api/v1/orders/{"{id}"} キャンセル

Schemas: OrderCreate · OrderResponse · ErrorResponse

bundle後の openapi.bundled.yaml から生成。

src/api/types/orders.ts

自動生成型（PG向け）

orders.ts

1// generated by Orval — DO NOT EDIT

2export interface OrderCreate {

3 customerId: string;

4 lines: OrderLine[];

手書きDTOを増やさない。

オンボーディング — API コース D 補助（確認 3 問）

#	問題	正解
1	OpenAPI 正本は1ファイル巨大 YAML か	分割 YAML + CI bundle
2	FE/BE 不一致の検知	schema diff · 型生成
3	破壊的変更時	ADR + バージョン方針