Swagger-codegen: [Jaxrs-spec] Improvements for Jaxrs-spec

[jfiala]

Description

• the api is generated as class, but IMHO this should be an interface!?
• javax.ws.rs.core.Response is used instead of the real response data type
• @ApiResponse uses wrong response type (the return type, not the response type of the contract)
• src/gen/java is not added to the build path
• "Attachment" is used for attachments, but no import is added for this (I think org.apache.cxf.jaxrs.ext.multipart.Attachment is referenced, but this is CXF-specific)
  (see also #4327)

Swagger-codegen version

2.2.2-SNAPSHOT

Related issues

4327

Suggest a Fix

• [x] generate api as interface (which then can be easily implemented)
  > changed in api.mustache, added new apiServiceImpl.mustache for implementation class
  
  
  
  • use real response data types instead of javax.ws.rs.core.Response (x)
    
    > should be changed separately see #4713
  
  
• [x] fix * @ApiResponse data types
  >>> fixed in AbstractJavaJAXRSServerCodegen by adding a check for void for api-response:

// set vendorExtensions.x-java-is-response-void to true as dataType is set to "void"
                        if ( resp.dataType == null ) {
                            resp.vendorExtensions.put("x-java-is-response-void", true);
                        }

and in api.mustache by adding the check for void and by using the baseType instead of returnType of @ApiReponse.

@ApiResponse(code = {{{code}}}, message = "{{{message}}}"{{^vendorExtensions.x-java-is-response-void}}, response = {{{baseType}}}.class{{/vendorExtensions.x-java-is-response-void}}

• [x] add src/gen/java to the buildpath
• [x] look for alternatives for JAXRS-compliant alternatives to org.apache.cxf.jaxrs.ext.multipart.Attachment or comment it out
  > as there is currently no standardized way for supporting multipart/form-data (see https://java.net/jira/browse/JAX_RS_SPEC-413), I changed formParams.mustache to

@FormParam(value = "{{paramName}}") InputStream {{paramName}}InputStream

This should be a sufficient standard hint, although it will have to be adapted for CXF/Jersey/Resteasy then.

[wing328]

generate api as interface (which then can be easily implemented)

I believe this will be a breaking change so better target 2.3.0 for this enhancement.

[jfiala]

If you don't want a breaking change, we could also add the interface with a suffix (e.g. "I" - "MyServiceI") and the class implementing the interface would only generate if it doesn't exist, thus making it non-breaking or add the interface approach as a library or separate language?

[jfiala]

Implemented solution at PR #4717, please review and advise if you prefer a non-breaking copy of the jaxrs-spec language or a breaking change for 2.3.0.

[ePaul]

as there is currently no standardized way for supporting multipart/form-data (see https://java.net/jira/browse/JAX_RS_SPEC-413), I changed formParams.mustache to

 @FormParam(value = "{{paramName}}") InputStream {{paramName}}InputStream

Please use {{baseName}} instead of {{paramName}} in all annotations which refer to the actual on-the-wire parameter name. (See #4898.)

[mamghari]

Hi @jfiala,

About the point:

• "javax.ws.rs.core.Response is used instead of the real response data type"

I think it is generally a bad practice for RESTful web services because whitout the Response object how do you manage the HTTP code returned ? How do you add HTTP Headers in your response?

It could be another option for the plugin but it is a bad practice... this is my point of view.

[Tillerino]

Hi @mamghari

IMO, a much cleaner way of handling response codes in JAX-RS is using WebApplicationException and its child classes. For example to return a 404, throw a NotFoundException from your endpoint. There are a bunch of exceptions shipped with the JAX-RS specification, you can extend WebApplicationException with your own exceptions and error codes, or even throw arbitrary ad-hoc exceptions using the various constructors of WebApplicationException - including specifying a Response object.

The clear benefit of this is that the interface shows your business logic and remains easily testable.

[keithchong]

I'm using the current online swagger editor to generate the jaxrs-spec server code from the example petstore definition. I'm seeing the unresolved (no import added) Attachment issue but also, I'm seeing an issue with the InputStream reference - it does not have an import as well:

public Response uploadFile(@PathParam("petId") @ApiParam("ID of pet to update") Long petId,@FormParam(value = "additionalMetadata")  String additionalMetadata, @FormParam(value = "file") InputStream fileInputStream, @FormParam(value = "file") Attachment fileDetail) {