Unused global response definition (OpenAPI 2.0)

Description

Responses defined in global responses are reused through operation references. Unused responses do not automatically make the specification invalid, but they can obscure the actual response contract.

Potential impact

Readers may be unsure which responses are returned, while maintainers keep unnecessary definitions up to date.

Remediation

Reference needed responses under the appropriate operation status codes. Check use by other documents as well, and remove only shared responses that are no longer needed.

Examples

These POST examples remove unused IllegalInput and GeneralError responses while retaining the referenced Success.

Before

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "$ref": "#/responses/Success"
          }
        },
        "parameters": [
          {
            "name": "limit2",
            "in": "body",
            "description": "max records to return",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "responses": {
    "Success": {
      "description": "200 response"
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error"
    }
  }
}

After