API文書を最新に保つ：コード変更後の6つの確認

API文書の更新はスキーマの反映だけでは完了しません。呼び出し側が何を送信し、何を受け取り、従来の使い方が有効かまで説明を合わせる作業です。

変更後の6つの確認

1. リクエストの必須・任意パラメータと既定値。
2. レスポンスのフィールド名、型、null許可。
3. 認証ヘッダー、権限、トークン要件。
4. エラーのステータスコードと処理方法。
5. コピーしたリクエストやコード例の実行。
6. 既存の呼び出し側への影響と移行案内。

フィールド名が変わる例

statusがpayment_statusに変わる状況を仮定します。名前の置換だけでは、値の意味や既存処理への影響が漏れることがあります。コミットとテストを確認し、旧フィールドの対応期間も記録しましょう。これは説明用の例で、顧客実績ではありません。

OpenAPIと説明文書

OpenAPIはHTTP APIのインターフェースを記述する標準です。スキーマがあっても、認証設定の理由、再試行の判断、移行手順は確認が必要です。公式仕様を参照し、インターフェース定義とチームの説明を分けて管理しましょう。Specifyが全てのOpenAPIツールと自動連携するという意味ではありません。

Specifyで修正案を確認する

GitHubのソースを文書プロジェクトに接続し、関連API文書を作成・管理します。変更前後と根拠を実際のインターフェースと照合してください。反映は設定と適用ポリシーに従います。GitHub連携ガイドから開始できます。

確認記録を残す

変更コミット、影響するエンドポイント、リクエスト・レスポンス、検証した例、互換性の判断、確認担当を記録しましょう。自動化で確認材料を準備し、実際の利用条件はチームで確認します。

機能紹介 · 開始する · オンボーディング文書