[JAXRS-CXF] Can't set HTTP code anymore

[markus-wa]

Description

Since #4068 the return code can't be set anymore as the *Api interface return values changed from javax.ws.rs.Response to generated models.

Generally this seems like a good move, but CXF now automatically sets the HTTP codes and, for example, always sends 204 for void returns.

Besides, custom success codes can't be set anymore at all.

Swagger-codegen version

2.2.2-SNAPSHOT

Swagger declaration file content or url

swagger: '2.0'
info:
  version: 1.0.0
  title: Wrong/forced return code example
host: example.com
basePath: /
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /example:
    get:
      responses:
        299:
          description:  Example

The resulting code will always end up returning 204.

Command line used for generation

java -jar swagger-codegen-cli.jar generate -i schema.json -l jaxrs-cxf

Steps to reproduce

--

Related issues

Pull #4068

Suggest a Fix

a) Go back to returning the generic javax.ws.rs.Response
b) Provide alternative way of setting the HTTP code

[jfiala]

@markus-wa I think setting the http response code should be done using exceptions, there you can set any return code you like (e.g. 404 NotFound, Not Authorized etc.). You also document these exceptions in the dynamic swagger contract using the swagger annotations.
So every method will return 200 by default, if you need exceptions use an exception.

I'm aware that this doesn't cover e.g. 201 created, if you really need javax.ws.rs.Response as return type, I suggest using it in the method signature, and use the swagger annotations to document which data type actually is returned, so using the original solution in a more consistent way.

[markus-wa]

Sorry, I am confused by

if you really need javax.ws.rs.Response as return type, I suggest using it in the method signature

what do you exactly mean by that?

For error codes I certainly agree it's best to use exceptions but it should still be possible to set the code for 2xx since the contract might define multiple responses with pre-defined or custom codes implying different results.

Whether that would be good practice or not is debatable.

I also noticed that

swagger: '2.0'
info:
  version: 1.0.0
  title: Wrong/forced return code example
host: example.com
basePath: /
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /example:
    get:
      responses:
        298:
          description:  Example
          schema:
            $ref: '#/definitions/A'
        299:
          description:  Example
          schema:
            $ref: '#/definitions/B'
definitions:
  A:
    type: object
    properties:
      x:
        type: string
  B:
    type: object
    properties:
      y:
        type: string

generates

@Path("/")
@Api(value = "/", description = "")
public interface DefaultApi  {

    @GET
    @Path("/example")
    @Consumes({ "application/json" })
    @Produces({ "application/json" })
    @ApiOperation(value = "", tags={  })
    public A exampleGet();
}

So it can only return type A but not B.

I'm aware that defining multiple responses of different types for one operation doesn't seem like a good idea but from what I can tell it's a valid swagger spec.

[jfiala]

I mean if you do code first you simply define

@Path("/")
@Api(value = "/", description = "")
public interface DefaultApi  {

    @GET
    @Path("/example")
    @Consumes({ "application/json" })
    @Produces({ "application/json" })
    @ApiOperation(value = "", tags={  })
    public javax.ws.rs.Response exampleGet();
}

to use multiple return codes with different types.

For contract first, I think we need a flag for the method to generate javax.ws.rs.Response instead of the default response type A currently used for such cases.

[jfiala]

Please also see OAI/OpenAPI-Specification#146 for a discussion about this topic, although it is about using different response types for the same response code.

[jfiala]

@wing328 do you have an idea how we can set a flag to default to javax.ws.rs.Response instead of the default response type?

[markus-wa]

I'd suggest a flag like useGenericWsResponse and just set the return type accordingly.

Is this also something that could be useful in other jaxrs-* type servers? I don't know how these handle response types etc. right now.

If so I could probably come up with a fix for each one.

As it will affect some of the same templates as #4569 that issue should probably be fixed first though.

[markus-wa]

@jfiala I filed PR #4829

[jfiala]

#4713 describes the same topic

[markus-wa]

#4713 seems to fit the topic better, as this one here is just about one symptom. Closing.