Incorrect response object reference (OpenAPI 2.0)

Description

A $ref in an operation’s response location must point to a Response Object. A body schema alone cannot replace the response object, which includes its description and can describe headers.

Potential impact

Response validation or documentation generation may fail, and clients may misunderstand the response contract.

Remediation

Reference shared responses through #/responses/..., and reference body models inside the response’s schema. External files are also valid when they provide the appropriate Response Object.

Examples

These POST examples replace the User schema reference in the response location with a reference to the Success response.

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": "#/definitions/User"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/limitParam"
          }
        ]
      }
    }
  },
  "responses": {
    "Success": {
      "description": "A user",
      "schema": {
        "$ref": "#/definitions/User"
      }
    }
  },
  "parameters": {
    "limitParam": {
      "name": "limit",
      "in": "body",
      "description": "max records to return",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  },
  "definitions": {
    "User": {
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  }
}

After