Generated but not references ResponseEntity*** type in schema if rest-api-class is using spring's ResponseEntity

[ahoehma]

I have such an interface:

import static org.springframework.http.MediaType.APPLICATION_JSON_VALUE;
import static org.springframework.http.MediaType.APPLICATION_PROBLEM_JSON_VALUE;

import jakarta.validation.constraints.NotBlank;
import jakarta.ws.rs.DELETE;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;

import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.DeleteMapping;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.ExampleObject;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;

@Validated
@Path(ConfigurationControllerApi.ConfiguratioApiPath.V1)
@RequestMapping(path = ConfigurationControllerApi.ConfiguratioApiPath.V1)
@SecurityRequirement(name = "basicScheme")
@ApiResponses(value = {
    @ApiResponse(
      responseCode = "400", description = "An validation error happens"),
    @ApiResponse(
      responseCode = "500", description = "Internal server error",
      content = {@Content(mediaType = APPLICATION_PROBLEM_JSON_VALUE, schema = @Schema(implementation = ProblemDetail.class))})})
public interface ConfigurationControllerApi {

// skip some constants for path, parameter names etc

@Operation( 
    summary = "Close a configuration.",
    description = "You must use this method to tell the service that a given configuration is no longer needed.",
    operationId = "closeConfiguration",
    tags = {
        ConfigurationApiTags.SERVICE,
        ConfigurationApiTags.REMOVE,
        ConfigurationApiTags.WRITE,
        ConfigurationApiTags.CONFIGURATION,
    })
  @ApiResponses(value = {
      @ApiResponse(
        responseCode = "200",
        description = "Ok",
        content = {
            @Content(mediaType = APPLICATION_JSON_VALUE, schema = @Schema(implementation = CloseConfigurationResult.class))
        }),
  })
  @DELETE
  @Path(ConfiguratioApiPath.CLOSE_CONFIGURATION)
  @Produces(APPLICATION_JSON_VALUE)
  @DeleteMapping(path = ConfiguratioApiPath.CLOSE_CONFIGURATION, produces = APPLICATION_JSON_VALUE)
  ResponseEntity<CloseConfigurationResult> closeConfiguration(
      @Parameter(description = "Id of the configuration you would like to close/destroy.") //
      @PathParam(value = ConfigurationApiParameter.CONFIGURATION_ID) //
      @PathVariable(value = ConfigurationApiParameter.CONFIGURATION_ID) //
      @NotBlank //
      @ConfigurationId // my own validation annotation
      String configurationId);
}

I run this in a maven build:

       <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin-jakarta</artifactId>
            <version>2.2.21</version>
            <configuration>
              <outputFormat>JSONANDYAML</outputFormat>
              <encoding>UTF-8</encoding>
              <sortOutput>true</sortOutput>
              <prettyPrint>true</prettyPrint>
              <readAllResources>false</readAllResources>
              <!-- see src/main/resources/META-INF/cc-api-openapi-defaults.yaml - filtered by maven during build with some values from cc top-level pom!-->
              <openapiFilePath>${project.build.outputDirectory}/META-INF/cc-api-openapi-defaults.yaml</openapiFilePath>
              <openapi31>false</openapi31>
            </configuration>
            <executions>
              <execution>
                <id>generate-api-cc-configuration</id>
                <goals>
                  <goal>resolve</goal>
                </goals>
                <configuration>
                  <contextId>configuration</contextId>
                  <outputPath>${project.basedir}/target/openapi-generated/v${api.version.new}/</outputPath>
                  <outputFileName>${cc.openapi.configuration.new}</outputFileName>
                  <resourceClasses>com.foobar.rest.api.ConfigurationControllerApi</resourceClasses>
                </configuration>
              </execution>
....

Everything works fine ... but as an additional result I got a generated but not references:

It seems ResponseEntity is handled by openapi generator but why?!

"ResponseEntityCloseConfigurationResult" : {
        "type" : "object",
        "properties" : {
          "body" : {
            "$ref" : "#/components/schemas/CloseConfigurationResult"
          },
          "headers" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "items" : {
                "type" : "string"
              }
            },
            "properties" : {
              "accept" : {
                "type" : "array",
                "items" : {
                  "$ref" : "#/components/schemas/MediaType"
                }
              },
              "acceptCharset" : {
                "type" : "array",
                "items" : {
                  "type" : "object",
                  "properties" : {
                    "registered" : {
                      "type" : "boolean"
                    }
                  }
                }
              },
              "acceptLanguage" : {
                "type" : "array",
                "items" : {
                  "type" : "object",
                  "properties" : {
                    "range" : {
                      "type" : "string"
                    },
                    "weight" : {
                      "type" : "number",
                      "format" : "double"
                    }
                  }
                }
              },
              "acceptLanguageAsLocales" : {
                "type" : "array",
                "items" : {
                  "type" : "object",
                  "properties" : {
                    "country" : {
                      "type" : "string"
                    },
                    "displayCountry" : {
                      "type" : "string"
                    },
                    "displayLanguage" : {
                      "type" : "string"
                    },
                    "displayName" : {
                      "type" : "string"
                    },
                    "displayScript" : {
                      "type" : "string"
                    },
                    "displayVariant" : {
                      "type" : "string"
                    },
                    "extensionKeys" : {
                      "type" : "array",
                      "items" : {
                        "type" : "string"
                      },
                      "uniqueItems" : true
                    },
                    "iso3Country" : {
                      "type" : "string"
                    },
                    "iso3Language" : {
                      "type" : "string"
                    },
                    "language" : {
                      "type" : "string"
                    },
                    "script" : {
                      "type" : "string"
                    },
                    "unicodeLocaleAttributes" : {
                      "type" : "array",
                      "items" : {
                        "type" : "string"
                      },
                      "uniqueItems" : true
                    },
                    "unicodeLocaleKeys" : {
                      "type" : "array",
                      "items" : {
                        "type" : "string"
                      },
                      "uniqueItems" : true
                    },
                    "variant" : {
                      "type" : "string"
                    }
                  }
                }
              },
              "acceptPatch" : {
                "type" : "array",
                "items" : {
                  "$ref" : "#/components/schemas/MediaType"
                }
              },
              "accessControlAllowCredentials" : {
                "type" : "boolean"
              },
              "accessControlAllowHeaders" : {
                "type" : "array",
                "items" : {
                  "type" : "string"
                }
              },
              "accessControlAllowMethods" : {
                "type" : "array",
                "items" : {
                  "$ref" : "#/components/schemas/HttpMethod"
                }
              },
              "accessControlAllowOrigin" : {
                "type" : "string"
              },
              "accessControlExposeHeaders" : {
                "type" : "array",
                "items" : {
                  "type" : "string"
                }
              },
              "accessControlMaxAge" : {
                "type" : "integer",
                "format" : "int64"
              },
              "accessControlRequestHeaders" : {
                "type" : "array",
                "items" : {
                  "type" : "string"
                }
              },
              "accessControlRequestMethod" : {
                "$ref" : "#/components/schemas/HttpMethod"
              },
              "all" : {
                "type" : "object",
                "additionalProperties" : {
                  "type" : "string"
                },
                "writeOnly" : true
              },
              "allow" : {
                "type" : "array",
                "items" : {
                  "$ref" : "#/components/schemas/HttpMethod"
                },
                "uniqueItems" : true
              },
              "basicAuth" : {
                "type" : "string",
                "writeOnly" : true
              },
              "bearerAuth" : {
                "type" : "string",
                "writeOnly" : true
              },
              "cacheControl" : {
                "type" : "string"
              },
              "connection" : {
                "type" : "array",
                "items" : {
                  "type" : "string"
                }
              },
              "contentDisposition" : {
                "$ref" : "#/components/schemas/ContentDisposition"
              },
              "contentLanguage" : {
                "type" : "object",
                "properties" : {
                  "country" : {
                    "type" : "string"
                  },
                  "displayCountry" : {
                    "type" : "string"
                  },
                  "displayLanguage" : {
                    "type" : "string"
                  },
                  "displayName" : {
                    "type" : "string"
                  },
                  "displayScript" : {
                    "type" : "string"
                  },
                  "displayVariant" : {
                    "type" : "string"
                  },
                  "extensionKeys" : {
                    "type" : "array",
                    "items" : {
                      "type" : "string"
                    },
                    "uniqueItems" : true
                  },
                  "iso3Country" : {
                    "type" : "string"
                  },
                  "iso3Language" : {
                    "type" : "string"
                  },
                  "language" : {
                    "type" : "string"
                  },
                  "script" : {
                    "type" : "string"
                  },
                  "unicodeLocaleAttributes" : {
                    "type" : "array",
                    "items" : {
                      "type" : "string"
                    },
                    "uniqueItems" : true
                  },
                  "unicodeLocaleKeys" : {
                    "type" : "array",
                    "items" : {
                      "type" : "string"
                    },
                    "uniqueItems" : true
                  },
                  "variant" : {
                    "type" : "string"
                  }
                }
              },
              "contentLength" : {
                "type" : "integer",
                "format" : "int64"
              },
              "contentType" : {
                "$ref" : "#/components/schemas/MediaType"
              },
              "date" : {
                "type" : "integer",
                "format" : "int64"
              },
              "empty" : {
                "type" : "boolean"
              },
              "etag" : {
                "type" : "string"
              },
              "expires" : {
                "type" : "integer",
                "format" : "int64"
              },
              "host" : {
                "type" : "object",
                "properties" : {
                  "address" : {
                    "type" : "object",
                    "properties" : {
                      "address" : {
                        "type" : "array",
                        "items" : {
                          "type" : "string",
                          "format" : "byte"
                        }
                      },
                      "anyLocalAddress" : {
                        "type" : "boolean"
                      },
                      "canonicalHostName" : {
                        "type" : "string"
                      },
                      "hostAddress" : {
                        "type" : "string"
                      },
                      "hostName" : {
                        "type" : "string"
                      },
                      "linkLocalAddress" : {
                        "type" : "boolean"
                      },
                      "loopbackAddress" : {
                        "type" : "boolean"
                      },
                      "mcglobal" : {
                        "type" : "boolean"
                      },
                      "mclinkLocal" : {
                        "type" : "boolean"
                      },
                      "mcnodeLocal" : {
                        "type" : "boolean"
                      },
                      "mcorgLocal" : {
                        "type" : "boolean"
                      },
                      "mcsiteLocal" : {
                        "type" : "boolean"
                      },
                      "multicastAddress" : {
                        "type" : "boolean"
                      },
                      "siteLocalAddress" : {
                        "type" : "boolean"
                      }
                    }
                  },
                  "hostName" : {
                    "type" : "string"
                  },
                  "hostString" : {
                    "type" : "string"
                  },
                  "port" : {
                    "type" : "integer",
                    "format" : "int32"
                  },
                  "unresolved" : {
                    "type" : "boolean"
                  }
                }
              },
              "ifMatch" : {
                "type" : "array",
                "items" : {
                  "type" : "string"
                }
              },
              "ifModifiedSince" : {
                "type" : "integer",
                "format" : "int64"
              },
              "ifNoneMatch" : {
                "type" : "array",
                "items" : {
                  "type" : "string"
                }
              },
              "ifUnmodifiedSince" : {
                "type" : "integer",
                "format" : "int64"
              },
              "lastModified" : {
                "type" : "integer",
                "format" : "int64"
              },
              "location" : {
                "type" : "string",
                "format" : "uri"
              },
              "origin" : {
                "type" : "string"
              },
              "pragma" : {
                "type" : "string"
              },
              "range" : {
                "type" : "array",
                "items" : {
                  "$ref" : "#/components/schemas/HttpRange"
                }
              },
              "upgrade" : {
                "type" : "string"
              },
              "vary" : {
                "type" : "array",
                "items" : {
                  "type" : "string"
                }
              }
            }
          },
          "statusCode" : {
            "$ref" : "#/components/schemas/HttpStatusCode"
          },
          "statusCodeValue" : {
            "type" : "integer",
            "format" : "int32"
          }
        }
      },