Incorrect response object reference (OpenAPI 3.0)

Description

A $ref for a status-code response must point to a Response Object. A data schema alone cannot replace an object that provides the response description and can describe headers and body formats.

Potential impact

Specification validation or documentation generation may fail, or clients may misunderstand the response format.

Remediation

Reference shared responses through #/components/responses/... and specify body schemas inside the response’s content. Valid external Response Objects are also supported.

Examples

These examples correct the Success reference path from schemas to responses.

Before

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "components": {
    "responses": {
      "Success": {
        "description": "200 response",
        "content": {
          "application/json": {
            "examples": {
              "foo": {
                "value": {
                  "versions": [
                    {
                      "status": "CURRENT",
                      "updated": "2011-01-21T11:33:21Z",
                      "id": "v2.0",
                      "links": [
                        {
                          "href": "http://127.0.0.1:8774/v2/",
                          "rel": "self"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    }
  }
}

After