Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#2,292 0 comments 0 reactions 0 assignees View on GitHub

@jacobps1 is already working on this.

Since Mar 24, 2026.

  • #2296 by @jacobps1 — open

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
52/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
java
Domain
api

Research direction

Start by reproducing the issue through OpenAPIParser.readContents with ParseOptions resolve and resolveFully enabled, using the request-body and parameter examples shown. Trace how the parser handles the content examples and compare both locations; done means each example reference is replaced by the referenced example data in the parsed OpenAPI result, with regression coverage for both cases.

Written by the indexing model from the issue text.

Description

Bug

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.
Dominant language
Java
Stars
868
Forks
560
Avg merge
7m
Merged PRs (30d)
2

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from swagger-api/swagger-parser

All issues in swagger-api/swagger-parser

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.