[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 JavaJaxRS spec : formParam uses Attachment which is CXF specific #4327)

Swagger-codegen version

2.2.2-SNAPSHOT

Related issues

#4327

Suggest a Fix

• 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

• 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}}

• add src/gen/java to the buildpath
• 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.