Being able to see the class within an EntityModel as a Schema

[chrisatrotter]

Is your feature request related to a problem? Please describe.

When wrapping a class in a EntityModel, then it would be useful to have that class unwrapped and shown as a Schema from the api-docs. This would be similar to how a class in a CollectionModel gets unwrapped and shown as a Schema from the api-docs.

This is how both EntityModel and CollectionModel are currently represented:

EntityModel

"components":{ 
    "schemas":{ 
       "EntityModel_Example_":{ 
          "type":"object",
          "properties":{ 
             ...
             "_links":{ 
                "$ref":"#/components/schemas/Links"
             }
          }
       }
    }
 }

CollectionModel

"components":{ 
    "schemas":{ 
       "CollectionModel_Example_":{ 
          "type":"object",
          "properties":{ 
             "_embedded":{ 
                "type":"object",
                "additionalProperties":{ 
                   "type":"array",
                   "items":{ 
                      "$ref":"#/components/schemas/Example"
                   }
                }
             },
             "_links":{ 
                ...
             }
          }
       },
       "Example":{ 
          "type":"object",
          "properties":{ 
             ...
          }
       }
    }
 }

Describe the solution you'd like
It would be useful to see the class that the EntityModel holds as a Schema.

EntityModel

"components":{ 
    "schemas":{ 
       "EntityModel_Example_":{ 
          "type":"object",
          "properties":{
             ...
             "_links":{ 
                "$ref":"#/components/schemas/Links"
             },
          }
       },
       "Example":{ 
          "type":"object",
          "properties":{
             ...
          }
       }
    }
 }

Describe alternatives you've considered
None so far

Additional context
None

[chrisatrotter]

Is this issue ambiguous? Should I rephrase the feature request?

[bnasslahsen]

@chrisatrotter,

Can you be more specific by adding:

• What version of spring-boot you are using?
• What modules and versions of springdoc-openapi are you using?
• What are the actual and the expected result using OpenAPI Description (yml or json)?
• Provide with a minimal sample (Java) code (HelloController) or Test that reproduces the request.

[bnasslahsen]

Issue closed as not feedback.

[AndreasRStensbye]

Sorry it took some time, here is a more detailed explanation and answers to your questions:

• What version of spring-boot you are using? 

We are using 1.2.32

• What modules and versions of springdoc-openapi are you using? 

Springdoc-openapi-ui and springdoc-openapi-data-rest

• What are the actual and the expected result using OpenAPI Description (yml or json)? 

Lets take a step back and look at what we are trying to achieve and why:

With the old springfox implementation we would get this when we wrapped a class with EntityModel:

EntityModel«MyAwesomeExampleClass»	{
_links	Links{...}
awesomeString*	string
awesomeName*	string
}

And it also provides a schema for the MyAwesomeExampleClass itself:

MyAwesomeExampleClass	{
awesomeString*	string
awesomeName*	string
}

Look how awesome it is, standing there proud independent of the EntityModel that is wrapping it, free by itself without “_links”. This is what we are missing in springdoc.

Springdoc gives:

EntityModelMyAwesomeExampleClass	{
awesomeString*	string
awesomeName*	string
_links	Links{...}

But no schema is given for MyAwesomeExampleClass. And this is a shame, and since it is so awesome of course I want to see it by itself in all its glory. Right now it is mixed with EntityModel, and if those poor front-end people are to look at it, how will they know what fields belong to MyAwesomeExampleClass and what belongs to the EntityModel?
Am I supposed to trust front-end to have intimate knowledge of how EntityModel is build up? No, I want to make it easy for them so that they see the schema for my class and knows exactly what to expect from my class.

I want classes that are wrapped in EntityModel to gain its own schema. And following HAL specification (https://apigility.org/documentation/api-primer/halprimer), the schema for the EntityModel puts the class under a "_embedded".

Springdoc already support this for things wrapped with CollectionModel.

And we also get a schema for EntityModelMyAwesomeExampleClass itself. We simply want springdoc to also give schemas for things wrapped with EntityModel, similarly to how things wrapped with CollectionModel gets their own schema.

• Provide with a minimal sample code.

Example code is in Kotlin
Code : ExampleController.zip

Explanation of results in springdoc-ui :

@RestController
class ExampleController(){
@ApiResponse(responseCode = "200", description =  "OK")
  @GetMapping("/example")
  fun getMyAwesomeClass(): EntityModel<MyAwesomeClass> {
      return EntityModel(
                  MyAwesomeClass(awesomeName = "Great", awesomeString = "sample text"),
                  linkTo(methodOn(ExampleController::class.java).getMyAwesomeClass()).withSelfRel())
  }
  @ApiResponse(responseCode = "200", description =  "OK")
  @GetMapping("/example2")
  fun getMyAwesomeClass2(): MyAwesomeClass {
      return MyAwesomeClass(awesomeName = "Great", awesomeString = "sample text")
  }
}
data class MyAwesomeClass(
      @field:Schema(required = true) val awesomeString: String,
      @field:Schema(required = true) val awesomeName: String
)

If we have an endpoint that returns MyAwesomeClass wrapped in en EntityModel, springdoc-ui does not show any schema for MyAwesomeClass as depicted in the figure:

Today, if I want a schema for myAwesomeClass, I need to add an endpoint that returns the class without it being wrapped in a ModelEntity. En example of this is :

  @ApiResponse(responseCode = "200", description =  "OK")
    @GetMapping("/example2")
    fun getMyAwesomeClass2(): MyAwesomeClass {
        return MyAwesomeClass(awesomeName = "Great", awesomeString = "sample text")
    }

This gives a schema for my class, as shown in the picture under. But I do not want to have to create an endpoint like that to get the schema automatically generated, but rather that it is generated if a EntityModel wrapps it.

[bnasslahsen]

Hi @chrisatrotter,

springdoc-open-api removes broken reference definition.
If you have noticed, the generated EntityModel only contains the attributes of your class MyAwesomeExampleClass.
If this answers your request, the following property will be added to the next release, so you can be able to see MyAwesomeExampleClass schema, even its not referenced directly:

springdoc.remove-broken-reference-definitions=false