Прежде всего, в следующем репозитории есть весь код (и описание), чтобы воспроизвести эту проблему: https://github.com/elgleidson/swagger-problem
У меня есть следующее JSON:
{
"nonNullableField": "not null",
"nullableField": null,
"nonNullableObjectField": {
"someField": "some value"
},
"nullableObjectField": null,
"nonNullableList": [
"not null"
],
"nullableList": null,
"nonNullableObjectList": [
{
"someField": "some value"
}
],
"nullableObjectList": null
}
, который сопоставлен со следующими Java классами:
@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;
}
При I go до /v3/api-docs (или /swagger-ui.html) генерируется следующая документация:
{
"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
}
}
Как видите, для полей, типы которых не сопоставлены с object, документация генерируется, как ожидается. То же самое не происходит для nullableObjectField: свойство nullable помещается в определение MyClass вместо поля.
Вместо этого я хотел бы создать следующую документацию:
{
"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"
}
}
Как я могу это сделать? Является ли это возможным?