swagger-core: Wrong documentation when nullable property is used in a field that maps to object
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.
The following documentation should be generated 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"
}
}
About this issue
- Original URL
- State: closed
- Created 7 years ago
- Reactions: 10
- Comments: 18 (5 by maintainers)
Is there any progress on this issue?
any progress?
Any progress?
In regards to the
$refdefinition, I see it as a contradiction between its definition:And its implementation:
Their example makes things even weird: a
Datecould be used as “date of birth”, not nullable, no defaults, in one place, but being used as a “end date”, nullable, in other place.How nobody thought that a component that’s suppose to be reused in many places could:
I hope they can review this design/implementation decision in a 3.2.x API definition.
Anyway, I appreciated the time you spent replying to my issue.
@micryc Thank you, i have switched to 3.1 and now schema is generated properly I see: “paidWallet”: { “$ref”: “#/components/schemas/MoneyAmount”, “title”: “Amount paid from wallet” }, “paidCard”: { “$ref”: “#/components/schemas/MoneyAmount”, “title”: “Amount paid from card” } It was incorrect before 3_1: “paidWallet”: { “$ref”: “#/components/schemas/MoneyAmount” }, “paidCard”: { “$ref”: “#/components/schemas/MoneyAmount” }
The minor problem is titles are not displayed with 3_1 in swagger-ui, but this is other problem I will probably figure this out some day…
So I think this issue is resolved.
Hello 😃
Any progress on this bug ?