First of all, the following repository has all the code (and description as well) to reproduce this problem: https://github.com/elgleidson/swagger-problem
I have the following JSON:
{
"nonNullableField": "not null",
"nullableField": null,
"nonNullableObjectField": {
"someField": "some value"
},
"nullableObjectField": null,
"nonNullableList": [
"not null"
],
"nullableList": null,
"nonNullableObjectList": [
{
"someField": "some value"
}
],
"nullableObjectList": null
}
Which is mapped to the following Java classes:
@Value
public class MyResponse {
@Schema(nullable = false, description = "DO NOT map to json object and DO NOT allow null")
private final String nonNullableField = "not null";
@Schema(nullable = true, description = "DO NOT map to json object and allows null")
private final String nullableField = null;
@Schema(nullable = false, description = "map to json object and DOES NOT allow null")
private final MyClass nonNullableObjectField = new MyClass(nonNullableField);
@Schema(nullable = true, description = "map to json object and allows null")
private final MyClass nullableObjectField = null;
@ArraySchema(arraySchema = @Schema(nullable = false, description = "list that DOES NOT map to json object and DOES NOT allow null"))
private final List<String> nonNullableList = List.of(nonNullableField);
@ArraySchema(arraySchema = @Schema(nullable = true, description = "list that DOES NOT map to json object and allow null"))
private final List<String> nullableList = null;
@ArraySchema(arraySchema = @Schema(nullable = false, description = "list that map to json object and DOES NOT allow null"))
private final List<MyClass> nonNullableObjectList = List.of(nonNullableObjectField);
@ArraySchema(arraySchema = @Schema(nullable = true, description = "list that map to json object and allow null"))
private final List<MyClass> nullableObjectList = null;
}
@Value
@Schema(description = "my class description")
public class MyClass {
@Schema(description = "my class field description")
private final String someField;
}
When I go to /v3/api-docs (or /swagger-ui.html) the following documentation is generated:
{
"MainResponse": {
"type": "object",
"properties": {
"nonNullableField": {
"type": "string",
"description": "DO NOT map to json object and DO NOT allow null"
},
"nullableField": {
"type": "string",
"description": "DO NOT map to json object and allows null",
"nullable": true
},
"nonNullableObjectField": {
"$ref": "#/components/schemas/MyClass"
},
"nullableObjectField": {
"$ref": "#/components/schemas/MyClass"
},
"nonNullableList": {
"type": "array",
"description": "list that DOES NOT map to json object and DOES NOT allow null",
"items": {
"type": "string"
}
},
"nullableList": {
"type": "array",
"description": "list that DOES NOT map to json object and allow null",
"nullable": true,
"items": {
"type": "string"
}
},
"nonNullableObjectList": {
"type": "array",
"description": "list that map to json object and DOES NOT allow null",
"items": {
"$ref": "#/components/schemas/MyClass"
}
},
"nullableObjectList": {
"type": "array",
"description": "list that map to json object and allow null",
"nullable": true,
"items": {
"$ref": "#/components/schemas/MyClass"
}
}
}
},
"MyClass": {
"type": "object",
"properties": {
"someField": {
"type": "string",
"description": "my class field description"
}
},
"description": "my class description",
"nullable": true
}
}
As you can see, for the fields whose types are not mapped to object the documentation is generated as expected. The same doesn't happen for nullableObjectField: the nullable property is put in MyClass definition instead of the field.
I would like to generate the following documentation instead:
{
"MainResponse": {
"type": "object",
"properties": {
"nonNullableField": {
"type": "string",
"description": "DO NOT map to json object and DO NOT allow null"
},
"nullableField": {
"type": "string",
"description": "DO NOT map to json object and allows null",
"nullable": true
},
"nonNullableObjectField": {
"$ref": "#/components/schemas/MyClass",
"description": "map to json object and DOES NOT allow null"
},
"nullableObjectField": {
"$ref": "#/components/schemas/MyClass",
"description": "map to json object and allows null",
"nullable": true
},
"nonNullableList": {
"type": "array",
"description": "list that DOES NOT map to json object and DOES NOT allow null",
"items": {
"type": "string"
}
},
"nullableList": {
"type": "array",
"description": "list that DOES NOT map to json object and allow null",
"nullable": true,
"items": {
"type": "string"
}
},
"nonNullableObjectList": {
"type": "array",
"description": "list that map to json object and DOES NOT allow null",
"items": {
"$ref": "#/components/schemas/MyClass"
}
},
"nullableObjectList": {
"type": "array",
"description": "list that map to json object and allow null",
"nullable": true,
"items": {
"$ref": "#/components/schemas/MyClass"
}
}
}
},
"MyClass": {
"type": "object",
"properties": {
"someField": {
"type": "string",
"description": "my class field description"
}
},
"description": "my class description"
}
}
How can I do that? Is it possible?
