OpenAPITools / OpenAPITools/openapi-generator
[Bug][Java][Spring] Missing description with Swagger2 annotations
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
I've noticed an issue when generating code using the Java Spring generator regarding the description when using Swagger2 annotations, i.e. the default option. The description is added to the JavaDoc, but not to the @Operation annotation.
The issue can be reproduced with 5.4.0, 6.0.0 and master.
- 5.4.0 lacks the description parameter at all
- 6.0.0 adds it, but it doesn't change anything
It's pretty simple to reproduce this issue. Here is a small example illustrating the issue:
paths:
/path:
get:
summary: Some short text
description: Some long text
responses:
200:
description: OK
This generates to the following (snip):
/**
* GET /path : Some short text
* Some long text
*
* @return OK (status code 200)
*/
@Operation(
summary = "Some short text",
responses = {
@ApiResponse(responseCode = "200", description = "OK")
}
)
@RequestMapping(
method = RequestMethod.GET,
value = "/path",
consumes = { "application/json" }
)
default ResponseEntity<Void> someMethod() {
return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
}
As you can see, it lacks the description within the @Operation annotation.
There is no special configuration needed, just use the defaults: generate -i test.yaml -g spring -o testgen
As far as I've understood to me it looks like there is a mismatch between the api.mustache file and Codegen structure. For the JavaDoc the template file uses notes, but for the description it tries to use description. As far as I can see in the DefaultCodegen#fromOperation only notes are set and therefore description is always empty/null/non-existing.
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 Spring generator's api.mustache template and DefaultCodegen#fromOperation, where the issue reports that only notes is populated. Reproduce the behavior with generate -i test.yaml -g spring -o testgen using the supplied OpenAPI example. Done means the generated @Operation annotation includes the path description, while the existing JavaDoc and response description remain correct.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, spring
- Domain
- backend-api-design, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100