[java] response return does not generate properly

[sashank]

Description

Response return with a string parameter should ideally generate the code with String. But in certain scenario it does not generate. This is consistent behaviour , easily reproducible.

Swagger-codegen version

any latest version

Swagger declaration file content or url

If the below response code is written for "CreateUser"

       '201':
          description: The request has been fulfilled, and a new resource is created .
          schema:
            type: "string"
            description: ID of the Object created

then as expected

public String createUser(User body)

but where as if below response code is written for "CreateUser"

      '200':
          description: OK. Request is OK.
       '201':
          description: The request has been fulfilled, and a new resource is created .
          schema:
            type: "string"
            description: ID of the Object created

notice the subtle change in the above that the first response code 200 does not return anything but second response code 201 returns String
now when we generate the code
public void createUser(User body)

Command line used for generation

java -jar /usr/share/swagger/swagger-codegen.jar generate -l java -c config.json -i index.yaml

Steps to reproduce

Very easy , just replace the above in pet store example and generate the code

Related issues/PRs

Suggest a fix/enhancement

It is not clear what is expected behavior , should we mention only one return response code ? or will the generator always take the return type of first response code ?
What is the appropriate behavior ?

[jmini]

I can confirm this issue.

Complete spec to test it:

openapi: 3.0.1
info:
  title: response test
  version: '1.0'
servers:
  - url: 'http://localhost:8000/'
paths:
  /myendpoint:
    post:
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: "string"
                description: ID of the Object created
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                type: "integer"
                format: int32
                description: ID of the Object created

Defining different response types is quite new with Swagger v3, this might be not supported yet.

[sashank]

The issue is in Swagger 2 too as well

[HugoMario]

thanks @sashank , i'll address this.

[upachler]

I am having a similar issue with two services, one is supposed to be returning 200 and 201, the other just 201.

TL/DR: My take on what the generator should do set the return type of a resource method (and currently doesn't):

if number of 2xx responses ==1 {
   if(status == 200) {
       return type is model type - if not defined, generate Response instead
   } else if(status == 204) {
       return type is void
   } else {
       return type is Response
   }
} else {
   return type is Response
}

On order to return 201 correctly, I need to be able to return a location header (see Mozilla's take on 201):
https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201

So if there's a 201 in the responses, I see no other choice for the generator to return a javax.ws.rs.core.Response instead of the actual response model type (no matter whether it's specified or not), because it is the only way to set the Location header. It also allows you to set any status.
This is particularly useful if your service has more than one response in the 2xx range (however, 3xx,4xx,5xx do not count, as they're usually not returned via Response, but via an Exception)

If you have multiple successful responses (more than one response in the 2xx range), the only way to set the actual status code is also to use Response as a return type (because you need to use Response.status([code]) to set the status code).

In the case of a single 204 response, the return type that makes most sense is void, because that's what JAX RS will convert into 204 without any further coding.