701-technologies-openapi

OpenAPI 3.x のベストプラクティス

HTTP のセマンティクスと利用者のニーズに沿った、保守しやすい OpenAPI 3.x コントラクトをチームが作成できるよう支援します。

このスキルで扱う内容

• ドキュメント構造：openapi、info、servers、tags、一貫性のあるリソースのグループ化
• パスとオペレーションの設計：パラメーター、リクエストボディ、レスポンスマトリックス、operationId、ステータスコード
• 再利用可能な components（スキーマ、パラメーター、レスポンス、セキュリティスキーム）と例
• 検証と CI：仕様のリンティング、破壊的変更のチェック、コード生成前のゲート
• コントラクトにおけるセキュリティのモデル化（スキーム、スコープ、グローバルとオペレーション単位のセキュリティ）
• コントラクトファースト設計とランタイム実装上の懸念事項の明確な境界

対象範囲： コントラクトファーストの品質のみです。このスキルでは、OpenAPI の設計、品質、ガバナンスに関するガイダンスに重点を置いてください。

制約

ユーザーが Java フレームワークとの統合を明示的に求めない限り、推奨事項は OpenAPI レイヤーにとどめてください。このリポジトリの XML ソースを編集した後は、スキルを再生成してビルドを検証してください。

• 必須：同じ変更セット内で Java または Maven の変更を提案する前に、./mvnw compile または mvn compile を実行してください
• フレームワーク：ガイダンスはコントラクト中心に保ち、フレームワーク固有のコントローラー接続やランタイムでの公開方法を規定しないでください
• ファジング：ファジングのガイダンスは高レベルかつコントラクト中心に保ち、外部スキル識別子へのリンクを含めないでください
• 検証：変更を推奨する前に、./mvnw clean verify または mvn clean verify を実行してください
• エッジケース：ユーザーの目標が曖昧な場合は、ファイルの編集やプロジェクト全体に対するコマンドの実行を始める前に中断し、確認の質問をしてください
• エッジケース：必要なコンテキスト、ファイル、認証情報、ツールが不足している場合は、障害となっている内容を明示して報告し、セットアップまたは代替のガイダンスのどちらで進めるかを尋ねてください
• エッジケース：要求された変更がプロジェクトの制約や安全上の境界に反する場合は、その矛盾を説明し、どのトレードオフを優先するかユーザーに確認してください

このスキルを使用する場面

• OpenAPI をレビューする
• OpenAPI を改善する
• API コントラクトを改善する
• API スキーマ設計を改善する
• OpenAPI 仕様を検証する

ワークフロー

1. リファレンスを読み、プロジェクトのコンテキストを評価する

変更を提案する前に、references/701-technologies-openapi.md を読み、現在の API およびコンテキストに関する成果物を確認してください。

2. 対象範囲を把握し、改善の対象を決める

求められている成果、制約、適用すべき最小限かつ安全な変更を特定してください。

3. 技術に沿った変更を適用する

リファレンスのパターンとプロジェクトの規約に従って、成果物を実装またはリファクタリングしてください。

4. 検証を実行し、結果を報告する

適切なチェックを実行し、変更内容、検証内容、フォローアップ事項を要約してください。

リファレンス

詳細なガイダンス、例、制約については、references/701-technologies-openapi.md を参照してください。