活用ガイド
リクエスト・レスポンス・認証・エラー・例がコードとずれないようにAPIドキュメントを維持する方法です。
APIドキュメントは、最も早くコードとずれてしまうドキュメントです。パラメーターが1つ、レスポンスフィールドが1つ変わっただけでも、ドキュメントを信じて連携した人はすぐに行き詰まります。Specifyは、エンドポイントのパラメーター、レスポンスフィールド、リクエスト例がコードとずれていないかを確認し、修正案を用意します。
設定する
APIのコードがあるリポジトリを接続する
ルート、ハンドラー、スキーマ定義があるリポジトリとブランチを、ドキュメントプロジェクトのソースとして接続します。スキーマが別のリポジトリにある場合は、ソースをもう1つ追加します。
APIリファレンスのドキュメントスキルを選択する
APIリファレンスを作成するドキュメントスキルを選択し、重視する点に対象読者（社内チーム、外部パートナーなど）と扱う範囲を書きます。
pushトリガーをオンにする
デフォルトブランチでpush で実行をオンにして、APIの変更が反映されるたびに修正案を受け取ります。
修正案をレビューするときに確認すること
| 領域 | 確認すること |
|---|---|
| リクエスト | パス、メソッド、パス・クエリパラメーター、リクエストボディのスキーマと必須かどうか |
| レスポンス | ステータスコードごとのレスポンスフィールド、型、nullableかどうか、ページネーションの形式 |
| 認証 | 必要な認証方式、権限スコープ、トークンを渡す場所 |
| エラー | エラーコードとメッセージ、再試行できるかどうか |
| 例 | リクエスト・レスポンスの例が新しいスキーマと一致しているか |
| 互換性 | フィールドの削除や名前の変更など、既存の連携を壊す変更かどうか、移行ガイドが必要かどうか |
既存の連携を壊す変更は、自動修正だけでは不十分な場合があります。変更履歴や移行ガイドが必要かどうかを人が判断し、補ってください。
コーディングエージェントと一緒に使う
Specify MCPを接続すると、Claude CodeやCodexがAPIを修正している間に、ワークスペースのAPIドキュメントを直接参照できます。ドキュメントとコードを同じ文脈で扱えるようになります。