Description
Schemas in definitions are used through references from requests, responses, or other models. An unreferenced schema can be valid, but unnecessary models make the actual data contract harder to maintain.
Potential impact
The effects of model changes may be harder to identify, and documentation may become unnecessarily complex.
Remediation
Check references from other schemas and external documents as well as direct uses. Reference needed models and remove only those no longer used.
Examples
These POST examples remove unused Tag while retaining Category, which is referenced by the request body.
Before
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"
}
}
}
}
}
After
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"
}
}
}
}
}