OpenAPI 3.0 オブジェクトの必須プロパティが不足

説明

OpenAPI 3.0 の各オブジェクトには必須プロパティがあります。例えば info には title と version、Response オブジェクトには description が必要です。必須プロパティが欠けると仕様書が不完全になり、文書表示やツールの処理に支障が生じる場合があります。

想定される影響

• API の識別情報や要求・応答の説明が不足する可能性があります。
• 仕様書の検証、文書生成、クライアント生成が失敗する場合があります。

対処方法

使用する OpenAPI のバージョンとオブジェクトの種類に応じて必須プロパティを確認し、実際の内容を記入してください。最上位の openapi、info、paths だけでなく、入れ子のオブジェクトも確認してください。変更後に仕様書全体を検証してください。

例

以下は info.title の不足を修正する例です。paths を空のオブジェクトにすることは許可されており、この例には API 操作を含めていません。

変更前

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "contact": {
      "name": "contact",
      "url": "/",
      "email": "user@gmail.com"
    }
  },
  "paths": {}
}

変更後

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0",
    "contact": {
      "name": "contact",
      "url": "/",
      "email": "user@gmail.com"
    }
  },
  "paths": {}
}

変更後は title と version の両方があり、API の基本的な識別情報を提供しています。実際の文書では、他のオブジェクトの必須プロパティも確認してください。

参考資料

• CWE-665
• OpenAPI Specification
• OpenAPI 3.0.3 仕様