springdoc-openapi
springdoc-openapi copied to clipboard
springdoc
Collection of class are not rendered/included in swagger ui/definition in OpenAPI version 3.1
I have spring boot application with simple REST endpoint, lombok and spring-doc dependency. When I have definition of REST response object, which includes collection of another object, it's definition is not rendered in swagger-ui and in definition JSON when OpenAPI version 3.1 is used in application configuration. It works in OpenAPI version 3.0 or in case that I included that object in collection as direct attribute.
@Schema(description="Some parent object")
@EqualsAndHashCode
@Builder(toBuilder = true)
@Value
public class SomeParentObject {
@Schema(description = "id")
long id;
@Schema(description = "list")
List<SomeChildObject> someList;
/* it will work if you uncomment this
@Schema(description = "other")
SomeChildObject other;*/
}
To Reproduce
- Have spring REST endpoint with response object which include collection of different object.
- There is no other direct attribute of that object other than the collection
- Set OpenAPI version 3.1 in settings
Dependency versions:
- Spring boot version 3.1.6
- springdoc-openapi-starter-webmvc-ui 2.3.0
- springdoc-openapi-starter-webmvc-api 2.3.0
- lombok 1.18.28
Expected behavior
- Object from the collection should be included in swagger UI and swagger endpoint JSON definition
OpenAPI version 3.1.0 definition
{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"http://localhost:8080","description":"Generated server url"}],"tags":[{"name":"Some","description":"some actions"}],"paths":{"/some/call":{"get":{"tags":["Some"],"summary":"Some summary","description":"Some operation description","operationId":"getSome","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SomeParentObject"}}}}}}}},"components":{"schemas":{"SomeParentObject":{"description":"Some parent object","properties":{"id":{"type":"integer","format":"int64","description":"id"},"someList":{"type":"array","description":"list","items":{"$ref":"#/components/schemas/SomeChildObject"}}}}}}}
OpenAPI version 3.0.1 definition
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"http://localhost:8080","description":"Generated server url"}],"tags":[{"name":"Some","description":"some actions"}],"paths":{"/some/call":{"get":{"tags":["Some"],"summary":"Some summary","description":"Some operation description","operationId":"getSome","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SomeParentObject"}}}}}}}},"components":{"schemas":{"SomeChildObject":{"type":"object","properties":{"id":{"type":"integer","description":"id","format":"int64"},"name":{"type":"string","description":"name"}},"description":"Some child object"},"SomeParentObject":{"type":"object","properties":{"id":{"type":"integer","description":"id","format":"int64"},"someList":{"type":"array","description":"list","items":{"$ref":"#/components/schemas/SomeChildObject"}}},"description":"Some parent object"}}}}
Screenshots
Minimalistic project to reproduce the problem spring-openapi-bug.zip
I tried to debug the problem and I found out that part, where reference to child list is removed is during call of this.removeBrokenReferenceDefinitions(openAPI); in AbstractOpenApiResource class.
There, during processing of references Array type is not resolved to ArraySchema object but everything is JSONSchema and condition in swagger-core-jakarta SpecFilter -> schema instanceof ArraySchema is not met.
As a workaround right now it can be fixed by disabling broken reference removal in application properties
springdoc.remove-broken-reference-definitions=false
