OpenApi generator not generating the "description" tag

Question

Given the below (snippet) of my spec

paths:
  /login:
    post:
      summary: "Method to login to obtain a JWT token"
      description: "Some description"
      operationId: login
      tags:
        - login
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Credentials"
          application/xml:
            schema:
              $ref: "#/components/schemas/Credentials"

and using the maven plugin with following config

              <plugin>
                <groupId>org.openapitools</groupId>
                <artifactId>openapi-generator-maven-plugin</artifactId>
                <version>5.4.0</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>
                                ${project.basedir}/src/main/resources/spec.yaml
                            </inputSpec>
                            <generatorName>spring</generatorName>
                            <apiPackage>com.company.api</apiPackage>
                            <modelPackage>com.company.model</modelPackage>
                            <modelNameSuffix>DTO</modelNameSuffix>
                            <typeMappings>
                                <typeMapping>Pageable=org.springframework.data.domain.Pageable</typeMapping>
                                <typeMapping>OffsetDateTime=LocalDateTime</typeMapping>
                            </typeMappings>
                            <importMappings>
                                <importMapping>java.time.OffsetDateTime=java.time.LocalDateTime</importMapping>
                            </importMappings>
                            <configOptions>
                                <dateLibrary>java8</dateLibrary>
                                <interfaceOnly>true</interfaceOnly>
                                <skipDefaultInterface>true</skipDefaultInterface>
                            </configOptions>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

The generated code looks like (cleaned up a bit to the relevant parts)

/**
     * POST /login : Method to login to obtain a JWT token
     * Some description
     *
     * @param credentialsDTO  (optional)
     * @return Login success (status code 200)
     *         or Unexpected error (status code 500)
     */
    @Operation(
        operationId = "login",
        summary = "Method to login to obtain a JWT token",
        tags = { "login" }
    )
    @RequestMapping(
        method = RequestMethod.POST,
        value = "/login",
        produces = { "application/json", "application/xml" },
        consumes = { "application/json", "application/xml" }
    )
    ResponseEntity<JWTTokenDTO> login(...)
    );

As shown, the 'description' from the spec is used to generate the JavaDoc, but in fact I'm expecting it to generate the 'description' attribute on @Operation tag.

I've searched for solutions, but I could not find the solution.

How can I correct this ?

Thanks in advance.

Answer 1

Unfortunately that can not be done simply by adjusting plugin configuration. Instead one must modify templates.

In this specific case it can be done as follows:

1. Fetch original template from: https://github.com/OpenAPITools/openapi-generator/blob/v5.4.0/modules/openapi-generator/src/main/resources/JavaSpring/api.mustache
2. Store it to src/main/resources/openapi/templates/api.mustache
3. Add templateDirectory to plugin configuration:

    <configuration>
    ...
        <templateDirectory>${project.basedir}/src/main/resources/openapi/templates</templateDirectory>
    </configuration>

4. Locate part of api.mustache that is template for @Operation from api.mustache (starts from line 130)

    @Operation(
        operationId = "{{{operationId}}}",
        {{#summary}}
        summary = "{{{.}}}",
        {{/summary}}

5. Add description attribute there (value comes from notes):

    @Operation(
        operationId = "{{{operationId}}}",
        {{#summary}}
        summary = "{{{.}}}",
        {{/summary}}
        {{#notes}}
        description = "{{{.}}}",
        {{/notes}}

More information about templating is available here: Using Templates