swagger-api / swagger-api/swagger-parser

Examples in the referenced paths are parsed differently than those in non-referenced paths.

Open
#2,111 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
867
Forks
560
Avg merge
2d 21h
Merged PRs (30d)
7

Description

Hello,

When using OpenAPI Specification where the operations of an endpoint are being referenced using another file, the examples are parsed as strings rather than objects in the absence of a reference.

schema_diff

As observed in the image above, the only distinction is that the operations under /products are referenced in V1, whereas no such reference exists in V2. When flattened out both V1 and V2 are identical. However, the example value and example type do not match when these specifications are parsed.

Expected Behavior

The examples in both V1 and V2 should be parsed consistently as JSON Object.

Actual Behavior

In V1, where the operations are referenced:

V1 Example Value: {id=1, name=XYZ Product, inventory=100}
V1 Example Value Type: class java.util.LinkedHashMap

In V2, where no reference exists:

V2 Example Value: {"id":"1","name":"XYZ Product","inventory":100}
V2 Example Value Type: class com.fasterxml.jackson.databind.node.ObjectNode

Sample Project

I have created a sample repository demonstrating this issue with the failing tests, which can be accessed here, Thank you for your attention to this matter.

Contributor guide

Open the contributing guide

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.

Research direction

Start with the failing tests in the linked swagger-parser-sample repository and compare how the V1 referenced operations and the non-referenced V2 are parsed. Trace the corresponding OpenAPI example handling in swagger-parser, then verify that equivalent examples produce JSON objects consistently in both cases.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.