Overriding responseClass

[dgershman]

Is there anyway to do this?

[conorroche]

my fork https://github.com/Carma-Public/swagger-jaxrs-doclet (which is for the swagger 1.2 spec and which i use for a large api https://api-dev.car.ma/apidoc/ref/index.html) supports this as well as per status code response types by adding a tag to the javadoc e.g.

/**
* @responseType fixtures.responsemodel.Response2
*/
@SuppressWarnings("javadoc")
@get
public Response responseDefinedViaTag() {
return Response.ok().entity(new Response2()).build();
}

see the test for fixtures.responsemodel in src/test

[cviebig]

@conorroche Is it hard to implement that for request objects also? We are using JsonView annotations extensively to serialize projections of our objects, i.e. hide certain attributes. Unfortunately most api documentation tools do not support that and show the full object with all it's properties

[conorroche]

@cviebig can you give me an example of what you mean by request objects?

I havent looked at Jsonview in terms of seeing how hard that will be, i did add support for removing fields/methods from the generated models/ and from the resources using the @deprecated tag/annotation.
I have just now added support for hiding model fields and methods and resource methods using the @hidden tag (other tags for excluding can be configured via -excludeMethodTags and -excludeFieldTags doclet options)

[cviebig]

@conorroche Sorry for being not clear enaugh. By request objects I mean for example JSON objects that are sent to the webservice via POST or PUT and automatically deserialized to be given to the method as a typed parameter. Swagger recognizes the type of those objects and displays all their properties but they're often having more properties than actually required for the operation. I wondered if it's easy to just display those properties that are actually needed, for example by specifying a dummy class having only those properties needed for this endpoint. I should not have mentioned JsonView annotations because they're only used for deserialization of response objects, sorry.

[conorroche]

do you mean something like this:

@POST 
/**
  * @inputType com.myclass.SmallNote
  */
public Response createNote(BigNote note)

where you want the generated docs to only describe the fields from the SmallNote class instead of the BigNote class?

its not hard to do but i wonder why you wouldnt just change the method to take the smaller object if thats all it needs? The only case i can think of is if there are some special hidden params which it can use but you dont want to document...

[cviebig]

Yes exactly, the doc annotation would also require the parameter name, but yes, that's it.

Well, good question, why not just use lighter objects? I decided to go this way because the deserializer complains about non-existing properties and I did not want to force API client developers to filter the object properties they send. This way they can just retrieve the object, work with it, and on changes send it back to the webservice or, use it as an embedded property value somewhere else to create relations where normally only the id property is required. Of course this is leads to some sort of more network overhead, but I think it should reduce the size of the glue code needed to communicate with the webservice.

[conorroche]

there can only be one body param e.g. non query/path param in post/put method signatures so no need for the param name.

you can use @JsonIgnoreProperties(ignoreUnknown = true) on the class to have it ignore extra fields which would allow you to set the param type as SmallNote and have it be sent json for BigNote

anyways ive added support for @inputType to my fork now.

[cviebig]

Thank you :)