説明
OpenAPI 2.0 では、異なるオブジェクトスキーマで同じプロパティ名を使用できます。例えば、複数のモデルに name があっても有効です。API 全体で名前を一意にするより、各オブジェクト内のデータの意味を明確に表すことが大切です。
想定される影響
- 異なる意味に曖昧な名前を使うと、API の利用者がデータを誤解する可能性があります。
- 使用中のプロパティを不要に改名すると、既存のクライアントとの互換性を損なう可能性があります。
対処方法
各オブジェクト内でプロパティの名前と意味を確認してください。他のモデルと名前が同じという理由だけで変更しないでください。共通の構造は必要に応じて $ref で再利用し、改名が必要な場合はクライアントの互換性と移行を計画してください。
例
以下の二つの本文スキーマは、それぞれ name、address、age を使用できます。参照先の Address 定義は省略しています。
変更前
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"basePath": "/api",
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
},
"parameters": [
{
"name": "limit2",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
},
"age": {
"type": "integer",
"format": "int32"
}
}
}
}
]
}
}
},
"parameters": {
"limitParam": {
"name": "limit",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
},
"age": {
"type": "integer",
"format": "int32"
}
}
}
}
}
}
変更後
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"basePath": "/api",
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
},
"parameters": [
{
"name": "limit2",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
},
"age": {
"type": "integer",
"format": "int32"
}
}
}
}
]
}
}
},
"parameters": {
"limitParam": {
"name": "limit",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "object",
"properties": {
"name_2": {
"type": "string"
},
"address_2": {
"$ref": "#/definitions/Address"
},
"age_2": {
"type": "integer",
"format": "int32"
}
}
}
}
}
}
変更後は再利用可能なパラメーターのプロパティに _2 を付けています。これは任意の API 契約の変更であり、モデル間の同名のプロパティをなくすための必須措置ではありません。意味が同じなら、元の名前を維持できます。