I currently am using openapi-generator to generate Spring Boot APIs based off a yaml spec. One endpoint in the yaml spec is supposed to return a map where the values are lists of enum values
{
"key1": ["EnumvVal1",...],
"Key2": ["EnumVal2", ...],
}
Currently, the response in the openapi spec is defined like this:
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
additionalProperties:
type: array
items:
type: MyEnum
The type MyEnum is an existing (non-generated) enum defined in my code, that the generator is configured to use via a an importMapping. My expectation is that the above spec should generate code/documentation that returns a Map<String, List<MyEnum>>, but it seems I am only half correct.
This is what openapi-generator actually produces in the API class:
@Operation(
operationId = "myMethod",
summary = "...",
description = "....",
tags = { "My Tag" },
responses = {
@ApiResponse(responseCode = "200", description = "OK", content = {
@Content(mediaType = "application/json", schema = @Schema(implementation = MyEnum.class))
})
}
)
@RequestMapping(
method = RequestMethod.GET,
value = "/some/path",
produces = { "application/json" }
)
default ResponseEntity<Map<String, List<MyEnum>>> myMethod() { ... }
The actual method is generated with the correct return type, as I would expect, but for some reason the openapi annotations specify the return value as just a single enum, as opposed to the more complex map type. This results in the generated swagger documentation being incorrect. Is this some issue with my openapi spec or a bug in the generator?
Currently I’m using the openapi-generator maven plugin version 7.8.0 for code generation.
1
There is no issue with your documentation format.
It was never implemented in the Swagger/OpenAPI to support @Schema with complex map type.
There is already a github issue available here – Document HashMap with @Schema.
FYI: This github issue talks about the problem that various people have faced with complex map type not being supported properly as users were expecting it to be.
Those people had the same issue like you had.
The last comment from the person who had closed the issue:
There were changes added by Francesco Tumanischvili in Swagger
Core (Committed files –#4475) modules to support
additionalPropertiesArraySchemain@Contentannotation which
should cover all use cases related toadditionalPropertiesto
support complex map type.
But there are not such documentation and tutorials available at the time of writing this answer to support the evidence on how it works with complex map type.
I also doubt that openapi-generator is even updated with these changes because I tried on my end to test all kinds of scenarios but it was not working.
0
You can use below syntax since OpenAPI doesn’t support MyEnum:
components:
schemas:
MyEnum:
type: string
enum:
- Val1
- Val2
# other values
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/MyEnum'