説明
OpenAPI 3.0 では、components.schemas にデータ構造を定義し、$ref で再利用できます。存在しないスキーマを参照すると、文書ツールが要求や応答のフィールドと型を解釈できない場合があります。
想定される影響
- 要求や応答の構造が文書に正しく表示されない可能性があります。
- コード生成や検証が失敗し、API 利用者がフィールドや型を誤って想定する場合があります。
対処方法
スキーマの $ref のパスと名前を、実在する Schema オブジェクトに合わせてください。ローカル参照は components.schemas の定義を、外部参照は対象文書とパスを確認してください。名前を変更した場合はすべての使用箇所を更新し、文書とデータ構造を検証してください。
例
応答の content 内で JSON スキーマを参照する例です。最初の例の MyWrongObject は定義されていません。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyWrongObject"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
変更後は MyObject を参照し、id と name を文字列として説明しています。スキーマは本文のデータ構造を定義するもので、応答全体の定義を置き換えるものではありません。