swagger-api / swagger-core

Examples and server integrations for generating the Swagger API Specification, which enables easy access to your REST API
http://swagger.io
Apache License 2.0
7.36k stars 2.17k forks source link

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

Open marco-brandizi opened 2 weeks ago

marco-brandizi commented 2 weeks ago

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.