Missing OpenAPI 3.0 example reference target

Description

OpenAPI 3.0 examples help readers understand request and response data. A local $ref naming an absent entry in components.examples prevents tools from displaying or reusing that example.

Potential impact

Documentation may omit or misrepresent request or response examples.
Reference errors may prevent validation or documentation generation.
API consumers may need more time to understand the data structure.

Remediation

Check that each example $ref resolves to the intended components.examples entry. Correct renamed, deleted or misspelled targets, and validate external reference URIs and targets as well. Check examples against the actual schema and media type.

Examples

The first document defines objectExample but references the missing wrongExample.

Before

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MyObject"
                },
                "examples": {
                  "objectExample": {
                    "$ref": "#/components/examples/wrongExample"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MyObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      }
    },
    "examples": {
      "objectExample": {
        "value": {
          "id": "1",
          "name": "new object"
        },
        "summary": "A sample object"
      }
    }
  }
}

After