Incorrect parameter object reference (OpenAPI 3.0)

Description

A $ref in a parameter location must point to a Parameter Object defining its name, location and other details. A schema or an incorrect reference path cannot provide the required parameter definition.

Potential impact

Validation or client generation may fail, or required parameter information may be omitted.

Remediation

Reference existing shared parameters under #/components/parameters/.... Valid Parameter Objects in external files are also supported.

Examples

These examples replace incorrect paths with the actual reference to idParam. The path parameter id matches {id} in the URL path.

Before

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API overview",
    "version": "1.0.0"
  },
  "components": {
    "parameters": {
      "idParam": {
        "name": "id",
        "in": "path",
        "description": "ID of the API version",
        "required": true,
        "schema": {
          "type": "integer"
        }
      }
    }
  },
  "paths": {
    "/{id}": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "parameters": [
        {
          "$ref": "#path/parameters/idParam"
        },
        {
          "$ref": "#components/schemas/idParam"
        }
      ]
    },
    "/user/{id}": {
      "get": {
        "parameters": [
          {
            "$ref": "#path/parameters/idParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}

After