Skip to content

[Bug]: content.examples $ref not resolved in request bodies or parameters #2292

@jacobps1

Description

@jacobps1

Description

When using resolveFully(true) to parse OpenAPI 3.0.x specs, $ref pointers within content.examples (in request bodies and parameters) are not resolved. The $ref remains as a pointer instead of being replaced with the referenced example.

Affected Version

  • 2.1.36

Steps to Reproduce

You can reproduce this issue by passing in an Open API 3.0.x spec with content examples into a parser with resolve options enabled.

String spec = """
   {
  "openapi": "3.0.3",
  "info": {
    "title": "Example Reference Demo API",
    "version": "1.0"
  },
  "paths": {
    "/users": {
      "post": {
        "summary": "Create a user",
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "simpleFilter": {
                    "$ref": "#/components/examples/FilterExample"
                  }
                }
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/User"
              },
              "examples": {
                "defaultUser": {
                  "$ref": "#/components/examples/UserExample"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      }
    },
    "examples": {
      "UserExample": {
        "summary": "A sample user",
        "value": {
          "id": "12345",
          "name": "John Doe"
        }
      },
      "FilterExample": {
        "summary": "A sample filter",
        "value": {
          "status": "active"
        }
      }
    }
  }
}
    """;

ParseOptions options = new ParseOptions();
options.setResolve(true);
options.setResolveFully(true);

SwaggerParseResult openAPIresult = new OpenAPIParser().readContents(spec, null, options);
OpenAPI result = openAPIResult.getOpenAPI();
System.out.println("OpenAPI result: " + result);

Expected Behavior

Content examples are resolved:

{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create a user",
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "content": {
              "application/json": {
                "schema": { "type": "object" },
                "examples": {
                  "simpleFilter": {
                    "summary": "A sample filter",
                    "value": { "status": "active" }
                  }
                }
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": { "type": "string" },
                  "name": { "type": "string" }
                }
              },
              "examples": {
                "defaultUser": {
                  "summary": "A sample user",
                  "value": { "id": "12345", "name": "John Doe" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Created" } }
      }
    }
  }
}

Actual Behavior

Content examples remain as $ref pointers:

{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create a user",
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "content": {
              "application/json": {
                "schema": { "type": "object" },
                "examples": {
                  "simpleFilter": {
                    "$ref": "#/components/examples/FilterExample"
                  }
                }
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": { "type": "string" },
                  "name": { "type": "string" }
                }
              },
              "examples": {
                "defaultUser": {
                  "$ref": "#/components/examples/UserExample"
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Created" } }
      }
    }
  }
}

Logs / Stack Traces

N/A

Environment

  • Java version: 21
  • Build tool: Maven 3.9
  • OS: macOS

Additional Context

N/A

Checklist

  • I have searched the existing issues and this is not a duplicate.
  • I have provided sufficient information for maintainers to reproduce the issue.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions