swagger-api / swagger-api/swagger-core

@Schema applied to two getters of type JsonNode returns one definition only

Open
#4,697 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog
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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.