# API のバージョン管理と廃止

MoreLogin は各 OpenAPI ドキュメントの `info.version` に機械可読な契約スナップショットのバージョンを公開しています。バージョンはカレンダー形式 `YYYY-MM-DD` で、リクエスト URL のバージョンセグメントではなくドキュメント契約を示します。

## 互換性のルール

| 変更 | 分類 | ドキュメントでの扱い |
|  --- | --- | --- |
| 任意のリクエストフィールド、レスポンスフィールド、操作、列挙値の追加 | 追加的変更 | 変更履歴に記録し、すべてのローカライズ仕様を更新する |
| 実行時の動作を変えずに説明を明確化、または例を修正 | ドキュメント修正 | 連携の指針が変わる場合に記録する |
| 任意フィールドを必須化、フィールドや操作の削除・改名、許容値の縮小、既存セマンティクスの変更 | 破壊的変更 | 削除前に移行手段と個別にバージョン付けした契約を提供する |
| 操作に `deprecated: true` を付ける | 廃止予告 | 代替、告知日、そして承認後に予定削除日を記載する |


クライアントは業務ロジックが許す範囲で、未知のレスポンスフィールドと列挙値を無視すべきです。これにより追加的リリースによる破損を減らせます。

## 廃止のメタデータ

OpenAPI の操作が権威ある機械可読の記載場所です。廃止予告された操作には次を含める必要があります：

- `deprecated: true`
- 代替を示す説明、または代替がないことの明記
- API 変更履歴への告知エントリ
- 製品とゲートウェイの責任者が承認した後にのみ記載する予定削除日


現時点で共通の最短廃止期間は保証されていません。削除日が明示的に公開されるまで、クライアントはその操作をサポート対象として扱いつつ、移行を計画すべきです。

## 事実の source of truth

実行時の動作が常に権威です。OpenAPI、例、ローカライズ版、エンドポイント動作マニフェスト、変更履歴は契約の乖離を防ぐため CI で一括検証されます。

## 検証レベル

リポジトリの品質ゲートに合格すると、OpenAPI ファイル、例、リンク、ローカライズ版、ガバナンス成果物がリポジトリ内で整合していることが確認できます。

ページ表示チェックでは、代表的なドキュメントルートがクライアント側エラーなしで読み込まれ、表示されることを確認できます。

デプロイ済み API に対する認証付きスモークテストだけが、本番動作と公開契約の一致を証明できます。このリポジトリではそのテストを既定で実行しないため、本番検証を実施した場合はリリースノートに別途明記する必要があります。