説明
OpenAPI 2.0 オブジェクトの標準プロパティを誤記すると、ツールに拒否されたり無視されたりして、意図した定義が適用されない場合があります。標準フィールドとデータモデルのプロパティ名、許可された x- 拡張を区別する必要があります。
想定される影響
- 文書やクライアントの生成が失敗したり、必要な情報が欠けたりする可能性があります。
- スキーマの制約を誤記すると、ツールが意図したデータ構造を解釈できない場合があります。
対処方法
各 OpenAPI 2.0 オブジェクトのプロパティ名と位置を確認し、誤記を修正してください。拡張に対応するオブジェクトの独自メタデータには x- 接頭辞を使用してください。スキーマの properties 配下にあるデータフィールド名まで、仕様の標準フィールド名に変更する必要はありません。
例
最初の例は description を descripption、properties を propppperties と誤記しています。
変更前
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/{id}": {
"get": {
"summary": "List API versions",
"responses": {
"200": {
"description": "OK"
}
},
"operationId": "listVersionsv2"
},
"parameters": [
{
"descripption": "ID of pet to use",
"required": true,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "csv",
"name": "id",
"in": "path"
}
]
}
},
"definitions": {
"ErrorModel": {
"type": "object",
"required": [
"message",
"code"
],
"propppperties": {
"message": {
"type": "string"
},
"code": {
"type": "integer",
"minimum": 100,
"maximum": 600
}
}
}
}
}
変更後
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/{id}": {
"get": {
"summary": "List API versions",
"responses": {
"200": {
"description": "OK"
}
},
"operationId": "listVersionsv2"
},
"parameters": [
{
"description": "ID of pet to use",
"required": true,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "csv",
"name": "id",
"in": "path"
}
]
}
},
"definitions": {
"ErrorModel": {
"type": "object",
"required": [
"message",
"code"
],
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "integer",
"minimum": 100,
"maximum": 600
}
}
}
}
}
変更後は標準プロパティ名を正しく使用しています。独自の拡張が必要な場合は、対象オブジェクトで許可される拡張規則に従ってください。