ops(openapi): $ref + sibling description (OAS 3.1) のツール互換性検証 (PR #179 follow-up)

[win2cot]

背景

PR #179(OpenAPI v1.4.4)で、Conflict / NotFound レスポンスを $ref + sibling description パターンで上書きする方式を採用した。これは OpenAPI 3.1 仕様(JSON Schema 2020-12 採用)で正式に valid な記法だが、ツール側のサポートは不均一:

• OpenAPI 3.0.x では $ref の兄弟キーは無視される(後方互換性のため)
• Swagger UI / Redoc / openapi-generator / spectral lint 等のバージョンによって、3.1 の sibling description を正しく扱うかは異なる

PR #179 のレビューで「ツール互換性事前確認推奨」が継続的に指摘された(計 3 回)。本フェーズはドキュメントのみで実害なしだが、Sprint 0 実装フェーズでクライアントコード生成 / API ドキュメント公開を行う段階で検証必須。

やること(Sprint 0 実装フェーズで対応)

主要ツールで本リポジトリの api/openapi.yaml(v1.4.4 以降)を実際に通し、sibling description が期待どおり上書き表示されるか検証する。

検証対象(候補)

• Swagger UI: API ドキュメント表示で description が各エンドポイントの具体的シナリオに上書きされているか
• Redoc: 同上
• openapi-generator(Java/TypeScript クライアント): 生成されたエラー型・docstring に description が反映されているか
• spectral lint: 仕様違反としてフラグされないか(本来は valid)
• swagger-cli validate: パース通過確認

検証結果による分岐

• 主要ツールで上書き機能が動作 → 現状の記法を維持
• 一部ツールで上書き無視 → 別 PR で代替記法に切り替え:
  • 候補 1: 各エンドポイントで $ref を使わず完全インライン化(冗長だが互換性確保)
  • 候補 2: description 部分だけ別パターン(例: responses の summary 等)

受け入れ条件

• 主要ツール 3 種以上で動作確認結果が記録されている
• 結果に応じた対応方針(現状維持 / 代替記法切替)が文書化されている
• 必要なら別 PR で OpenAPI 改訂

参照

• 親 Issue: [Phase 1 Sprint 0] scaffold ↔ 設計書 v1.4.x 整合実装(2 週間、2026-06-14 〜 06-27) #121 [Sprint 0] scaffold ↔ 設計書 v1.3 整合実装
• 派生元 PR: api(openapi): v1.4.4 — info.description 共通レスポンス補完 + Conflict/NotFound description 具体化 + AuditLog 補強 (Issues #127 #128 #173 #174) #179(OpenAPI v1.4.4)
• 関連: 設計規約 §2.1 OpenAPI ファースト(クライアントコード生成・API契約凍結の前提)

[win2cot]

検証結果レポート

検証環境

• 検証対象: api/openapi.yaml(v1.4.4 以降)の $ref + sibling description パターン、17 箇所
• 実施日: 2026-06-01
• 実施方法: Docker コンテナで各ツールをローカル実行

---

ツール別結果

1. Spectral lint (stoplight/spectral:6)

結果: ✅ エラー・警告ゼロ

No results with a severity of 'error' found!

OAS 3.1 仕様として valid 判定。$ref + sibling description は仕様違反フラグなし。

---

2. swagger-cli validate (@apidevtools/swagger-cli@4)

結果: ✅ パース通過

/api/openapi.yaml is valid

※ なお @apidevtools/swagger-cli 自体は deprecated(→ @redocly/cli への移行を推奨するメッセージが出た)。後述の Redocly CLI に実質引き継がれている。

---

3. Redoc (redocly/cli build-docs + bundle)

結果: ✅ sibling description が正しく使用される

redocly/cli bundle が出力した YAML では $ref + sibling description の両方が保持され、最終的な HTML(build-docs)では sibling description テキストが 17 回 レンダリングされた。base description("リソース未存在…")は components 定義・サイドバー等に限定的に残る 3 回 のみ。

具体例:

# bundled.yaml — GET /api/tasks/{id} の 404
'404':
  $ref: '#/components/responses/NotFound'
  description: タスクが存在しないか、当該ユーザーが**参照権限**を持たない(可視性チェック不通過によりリソース存在を秘匿、HTTP Status Policy / NIST AC-4)。

生成 HTML でもこのシナリオ固有テキストが表示される → API ドキュメントとしての意図が達成されている。

---

4. openapi-generator (Java / openapitools/openapi-generator-cli)

結果: ⚠️ sibling description は無視 — base $ref description が使用される

コード生成自体は正常完了。ただし生成 Markdown ドキュメント(TaskApi.md 等)では 404 の description がすべて base description になっていた。

比較	テキスト
sibling description (openapi.yaml)	タスクが存在しないか、当該ユーザーが**参照権限**を持たない(可視性チェック…)
生成 TaskApi.md の 404 説明	リソース未存在、または参照権限不足(リソース存在を漏らさない方針)

ジェネレーター自身も OpenAPI 3.1 support is still in beta と WARN を出力しており、sibling key の扱いが未成熟な段階にある。

---

総合判断と対応方針

→ 現状の記法を維持する

観点	判断
仕様 valid か	✅ (OAS 3.1 / JSON Schema 2020-12 として正式 valid)
API ドキュメント(Redoc)	✅ sibling description が正しくレンダリングされる
CI lint (spectral)	✅ エラーなし
クライアントコード生成	⚠️ sibling 無視だが 機能的に問題なし — 生成クライアントに必要な型・メソッド・HTTP コードは正しく生成される。JavaDoc の 404 説明文が汎用テキストになるのは許容範囲

openapi-generator の sibling 無視は OAS 3.1 beta サポートの既知制限であり、インライン化等の代替記法に切り替えるコストに対してメリットが薄い。Sprint 0 実装フェーズでクライアントコード生成を本格利用する段階で openapi-generator のバージョンアップを確認し、sibling サポートが改善していれば追加対応は不要。

追加確認推奨: Swagger UI のブラウザ上での表示(Docker serve で手動確認)は今回の検証外。Redoc で動作確認済みのため優先度低と判断したが、公開 API ドキュメントを Swagger UI で提供する際は改めて確認すること。

[win2cot]

受け入れ条件を満たしたため Close。対応方針: 現状の $ref + sibling description 記法を維持。詳細は上記コメント参照。