swagger-api / swagger-api/swagger-core
@Schema applied to two getters of type JsonNode returns one definition only
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 7.5k
- Forks
- 2.3k
- Avg merge
- 18h 1m
- Merged PRs (30d)
- 10
Description
I'm trying to document the following class, which is returned by a Spring-based API:
public class CytoscapeJsWrapper
{
...
@Schema ( description =
"""
As per Cytoscape.js, this contains a 'data' element, containing node properties
(eg, id, type, label, and a few others). See /graphDetails for more information.
"""
)
public JsonNode getNodes ()
{
return nodes;
}
@Schema ( description =
"""
Same as /elements/nodes, with the addition of the 'source' and 'target' properties.
"""
)
public JsonNode getEdges ()
{
return edges;
}
}
The generated OpenAPI I can see at http://localhost:8080/v3/api-docs/v1:
...
"CytoscapeJsWrapper": {
"type": "object",
"properties": {
"nodes": {
"$ref": "#/components/schemas/JsonNode"
},
"edges": {
"$ref": "#/components/schemas/JsonNode"
}
},
"description": "The graph obtained from merging all the resulting semantic motif paths..."
}
...
And only one JsonNode definition in the components section:
...
"JsonNode": {
"type": "object",
"description": "Same as /elements/nodes, with the addition of the 'source' and 'target' properties.\n"
}
...
While it should apply both the @Schema annotations and describe the two different fields properly.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the generated document at /v3/api-docs/v1 from the two annotated JsonNode getters in CytoscapeJsWrapper. Trace how those getter annotations become the JsonNode component schema, then verify that the completed output preserves distinct descriptions for both nodes and edges.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi, spring
- Domain
- api, backend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100