説明
definitions のスキーマは、リクエスト、レスポンス、他のモデルから参照して使用します。参照されていないスキーマも有効ですが、不要なモデルが残ると実際のデータ契約を管理しにくくなります。
想定される影響
モデル変更の影響が分かりにくくなり、文書が必要以上に複雑になる可能性があります。
対処方法
直接の参照だけでなく、他のスキーマや外部文書での使用も確認してください。必要なモデルは参照し、不要になったモデルだけを削除してください。
例
次の POST の例では、未使用の Tag を削除し、リクエスト本文から参照される Category を残しています。
変更前
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
},
"parameters": [
{
"name": "category",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"$ref": "#/definitions/Category"
}
}
]
}
}
},
"definitions": {
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
}
}
}
変更後
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
},
"parameters": [
{
"name": "category",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"$ref": "#/definitions/Category"
}
}
]
}
}
},
"definitions": {
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
}
}
}