# APIドキュメントを最新に保つ

> リクエスト・レスポンス・認証・エラー・例がコードとずれないようにAPIドキュメントを維持する方法です。

APIドキュメントは、最も早くコードとずれてしまうドキュメントです。パラメーターが1つ、レスポンスフィールドが1つ変わっただけでも、ドキュメントを信じて連携した人はすぐに行き詰まります。Specifyは、エンドポイントのパラメーター、レスポンスフィールド、リクエスト例がコードとずれていないかを確認し、修正案を用意します。

## 設定する

<Steps>
  <Step title="APIのコードがあるリポジトリを接続する">
    ルート、ハンドラー、スキーマ定義があるリポジトリとブランチを、ドキュメントプロジェクトのソースとして接続します。スキーマが別のリポジトリにある場合は、ソースをもう1つ追加します。
  </Step>
  <Step title="APIリファレンスのドキュメントスキルを選択する">
    APIリファレンスを作成するドキュメントスキルを選択し、重視する点に対象読者（社内チーム、外部パートナーなど）と扱う範囲を書きます。
  </Step>
  <Step title="pushトリガーをオンにする">
    デフォルトブランチで**push で実行**をオンにして、APIの変更が反映されるたびに修正案を受け取ります。
  </Step>
</Steps>

## 修正案をレビューするときに確認すること

| 領域 | 確認すること |
| --- | --- |
| **リクエスト** | パス、メソッド、パス・クエリパラメーター、リクエストボディのスキーマと必須かどうか |
| **レスポンス** | ステータスコードごとのレスポンスフィールド、型、nullableかどうか、ページネーションの形式 |
| **認証** | 必要な認証方式、権限スコープ、トークンを渡す場所 |
| **エラー** | エラーコードとメッセージ、再試行できるかどうか |
| **例** | リクエスト・レスポンスの例が新しいスキーマと一致しているか |
| **互換性** | フィールドの削除や名前の変更など、既存の連携を壊す変更かどうか、移行ガイドが必要かどうか |

<Warning>
  既存の連携を壊す変更は、自動修正だけでは不十分な場合があります。変更履歴や移行ガイドが必要かどうかを人が判断し、補ってください。
</Warning>

## コーディングエージェントと一緒に使う

[Specify MCP](/ja/mcp/overview)を接続すると、Claude CodeやCodexがAPIを修正している間に、ワークスペースのAPIドキュメントを直接参照できます。ドキュメントとコードを同じ文脈で扱えるようになります。