OpenAPITools / OpenAPITools/openapi-generator

[Bug][Java][Spring] Missing description with Swagger2 annotations

Open
#12,571 2 comments 3 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.