[Spring] can't handle multiple responses

[mwoodland]

Description

We have an OpenAPI spec file where we've defined multiple possible responses for an operation, however when the Spring code is generated the generated @RequestMapping method is only capable of returning the first response defined.

openapi-generator version

3.2.3

OpenAPI declaration file content or url

openapi: "3.0.0"
info:
  title: "Example"
  version: "1.0.0"
servers:
  - url: "/api/v1"
  - url: "/api/"
tags:
  - name: "example"
paths:
  "/example":
    get:
      tags:
        - "example"
      operationId: "examples"
      summary: "Get examples that match criteria"
      parameters:
      - name: "id"
        in: query
        description: "the identifier to get"
        required: true
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                $ref: "#components/schemas/ExampleObject"
        404:
          description: "Failed to find the Example Object"
          content:
            application/json:
              schema:
                $ref: "#components/schemas/Errors"
components:
  schemas:
    "ExampleObject":
      type: object
      properties:
        "property1":
          type: string
        "property2":
          type: string
    "Errors":
      type: object
      properties:
        "code":
          type: integer
          format: int32
        "severity":
          type: string
        "message":
          type: string

Command line used for generation

<pluginExecutor>
    <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>3.2.3</version>
    </plugin>
    <goal>generate</goal>
    <configuration>
        <inputSpec>api-def/spec.yml</inputSpec>
        <generatorName>spring</generatorName>
        <output>api-gen</output>
        <modelNamePrefix>Api</modelNamePrefix>
        <configOptions>
            <basePackage>package</modelPackage>
            <apiPackage>package</apiPackage>
            <groupId>group</groupId>
            <artifactId>api-gen</artifactId>
            <artifactVersion>${project.version}</artifactVersion>
            <artifactDescription>Automatically generated interfaces for APIs</artifactDescription>
            <interfaceOnly>true</interfaceOnly>
        </configOptions>
    </configuration>
</pluginExecutor>

Steps to reproduce

Generate the Spring code using the specified spec file and maven configuration.
The following @RequestMapping is generated:

    @ApiOperation(value = "Get examples that match criteria", nickname = "examples", notes = "", response = ApiExampleObject.class, tags={ "example", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "Success", response = ApiExampleObject.class),
        @ApiResponse(code = 404, message = "Failed to find the Example Object", response = ApiErrors.class) })
    @RequestMapping(value = "/example",
        produces = { "application/json" }, 
        method = RequestMethod.GET)
    default ResponseEntity<ApiExampleObject> examples(@NotNull @ApiParam(value = "the identifier to get", required = true) @Valid @RequestParam(value = "id", required = true)  ) {
        getRequest().ifPresent(request -> {
            for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
                if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
                    ApiUtil.setExampleResponse(request, "application/json", "{  \"property2\" : \"property2\",  \"property1\" : \"property1\"}");
                    break;
                }
            }
        });
        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

    }

The return type is of ResponseEntity<ApiExampleObject> which means I can't return an ApiErrors object.

Related issues/PRs

Sounds similar to #316

Suggest a fix/enhancement

Get the method to return an object that can encapsulate one of the types defined in the response.

Or a simpler option is to get the method to return a ResponseEntity<Object>.

[tilowestermann]

I wonder that this issue has such a low activity. Is there any recommended workaround, or do you plan to fix it in an upcoming release?

[alexjoybc]

Is there any update on this issue? we are facing the same problem where we have to return different objects depending on the status of the response....

[pmatysek]

Any news on it?
The only solution I've found is to edit api.mustache and add something like:
{{#responses.1}}ResponseEntity<?>{{/responses.1}} {{^responses.1}}{{>returnTypes}}{{/responses.1}}

[tigerinus]

Would be nice to support ResponseEntity<? extends Order> when we have allOf inheritance in the schema:

    OrderResponseOK:
      description: OK
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/Order"
            properties:
              message:
                readOnly: true
                type: string
                example: "OK"

[tloubrieu-jpl]

Hello,

I was coming back here to see if there is any progress on that.

If that can help, our workaround so far is to add a type 'object' to all of the possible response types so that the API end-point takes ResponseEntity as the default returned type.

We do it this way:

The end-point definition:

 /products/{identifier}/collections/latest:
    get:
      tags:
        - deprecated
      summary: deprecated
      operationId: products-lidvid-collections-latest
      responses:
        '200':
          $ref: "#/components/responses/Plural"
        '400':
          $ref: "#/components/responses/Error"
        '404':
          $ref: "#/components/responses/Error"
       ...

And:

responses:
   Error:
     description: Unsuccessful request
     content:
       "*":
         schema:
           type: object
       "*/*":
         schema:
           $ref: '#/components/schemas/errorMessage'
       application/csv:
         schema:
           $ref: '#/components/schemas/errorMessage'
       ...
   Plural:
     description: Successful request
     content:
       "*":
         schema:
           type: object
       "*/*":
         schema:
           $ref: '#/components/schemas/pdsProducts'
       application/csv:
         schema:
           $ref: '#/components/schemas/wyriwygProducts'
    ....

This does not look good, but we did not find a better work-around...

[massahud]

One workaround is to define all responses as Response and the schema like this:

    SuccessResponse:
      type: object
      properties:
        message:
          type: string

    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string

    Response:
      oneOf:
        - $ref: '#/components/schemas/SuccessResponse'
        - $ref: '#/components/schemas/ErrorResponse'

SuccessResponse and ErrorResponse models will implement Response, generated as an empty interface.

[davidmoten]

So I guess the controller method is typed based on what it thinks is the primary response. You can trick it to return something else because of generics type erasure:

 return (ResponseEntity<ApiExampleObject>)(ResponseEntity<?>) differentResponse;

I'm curious, why did the project owners not answer this? It's been open since 2018 and is a very important use-case with a simple answer.

[massahud]

@davidmoten why the thumbs down? Is there a problem with the workaround?

[davidmoten]

@davidmoten why the thumbs down? Is there a problem with the workaround?

No it's a valid workaround, I removed the thumbs down. Easier and generally more practical just to learn the casting trick but I do like the extra type safety your workaround gives. Not practical to rework large complex third-party apis just to get that feature though. It could be done by the openapi-generator generator where it creates a oneOf type class that also checks validity of type codes (without you having to do it).

[denis-dbm]

Up

Does this have preview of planning/release? This feature is useful for good design, code and api.