OpenAPITools / OpenAPITools/openapi-generator
[BUG] Documentation provider "springdoc" does not handle lists correctly
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
The springdoc documentation provider does not seem to use @ArraySchema when a response containing a list is returned by the API.
Steps to reproduce:
I am generating code by using this json swagger input:
https://tmf-open-api-table-documents.s3.eu-west-1.amazonaws.com/OpenApiTable/4.1.0/swagger/TMF620-ProductCatalog-v4.1.0.swagger.json (see also the attachment).
After calling:
java -jar openapi-generator-cli-5.4.0.jar generate -i TMF620-ProductCatalog-v4.1.0.swagger.json -g spring
I am getting this code tree:
src.zip
Having a look at this file:
src\main\java\org\openapitools\api\ProductOfferingApi.java
You will see this documentatin fot the GET operation:
@Operation(operationId = "listProductOffering", summary = "List or find ProductOffering objects",tags = { "productOffering" },
responses = {
@ApiResponse(responseCode = "200", description = "Success", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ProductOffering.class))),
@ApiResponse(responseCode = "400", description = "Bad Request", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "401", description = "Unauthorized", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "403", description = "Forbidden", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "404", description = "Not Found", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "405", description = "Method Not allowed", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "409", description = "Conflict", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Error.class))),
@ApiResponse(responseCode = "500", description = "Internal Server Error", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Error.class)))
}
)
@RequestMapping(
method = RequestMethod.GET,
value = "/productOffering",
produces = { "application/json;charset=utf-8" }
)
default ResponseEntity<List<ProductOffering>> listProductOffering(
@Parameter(name = "fields", description = "Comma-separated properties to be provided in response", schema = @Schema(description = "")) @Valid @RequestParam(value = "fields", required = false) String fields,
@Parameter(name = "offset", description = "Requested index for start of resources to be provided in response", schema = @Schema(description = "")) @Valid @RequestParam(value = "offset", required = false) Integer offset,
@Parameter(name = "limit", description = "Requested number of resources to be provided in response", schema = @Schema(description = "")) @Valid @RequestParam(value = "limit", required = false) Integer limit)
{...}
The line @ApiResponse(responseCode = "200", is wrong because an @ArraySchema is required here since the GET request delivers a list and not a single object.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the supplied TMF620 swagger input and reproduce the issue using the openapi-generator-cli 5.4.0 command. Inspect the generated src/main/java/org/openapitools/api/ProductOfferingApi.java and trace the Spring generator entry point or template responsible for the GET response annotation. Done means list responses use @ArraySchema rather than @Schema(implementation = ProductOffering.class).
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi, spring
- Domain
- api, backend, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100