support swagger annotated resources/models classes

[conorroche]

support swagger annotated resources/models classes, e.g. support swagger annotations so people can use this for their api json instead of all the additional javadoc tags, this would allow this to act as an alternative to other swagger tools

[rmpestano]

Just to confirm, i can't use : @ApiResponses(value = {
@ApiResponse(code = 404, message = "not found")
})

it will be ignored by the doclet right? there is any alternative to generate response api?

also for return types like: @ApiOperation(value = "FindById",, response = SomeEntity.class)

thanks in advance.

[conorroche]

yes these will be ignored until I have a chance to add support for them which is unlikely to be until the new year to be honest.
The alternative to using annotations like those is to use javadoc tags on the method so for your examples you would have the following:

/**
* @responseMessage 200 ok
* @responseMessage 404 not found com.mycompany.SomeEntity
*/
public Response findById(String id){
...
}

Out of curiosity if you already have source that uses the swagger annotations wouldn't you just use the

swagger jaxrs e.g. like in this article: http://jmchung.github.io/blog/2013/12/14/integrating-swagger-into-jax-rs-with-java-ee-6-specification/ or are you using it but want offline documentation?

[rmpestano]

I dont have swagger annotations, i was just wondering how to add response to the api. I really prefer using javadoc instead of proprietary annotations.

I also found in examples
/**

• @responseType SomeEntity
  */

to document return type. Where these javadoc annotations come from?

many thanks!

[conorroche]

If you take a look at the readme.md file https://github.com/Carma-Public/swagger-jaxrs-doclet#supported-javadoc-tags-and-annotations you will see a full list of all the supported javadoc tags. These tags are specific to this project.

[conorroche]

ahh i think i may have misunderstood you. Swagger supports both a default response model and a specific response model per different response code. The @responseType tag is for the normal response model. Using the @responseMessage tag allows you to add a different response model (usually a custom error entity) on a per response code basis

[rmpestano]

Yes, this was just what i was looking for.
I am facing a problem which is when i try to get a resource that doesnt not exist i return 404 but in swagger UI i hangs, eg:

 /**
- @responseMessage 404 resource not found
  */
  public Response merhod(){
  if (notFount()) {
    return Response.status(Status.NOT_FOUND).entity("some message").build();
  }
  }
  

am i missing something?

[rmpestano]

solved my problem(returning a string with content type json made swagger ui to hang). sorry to spam this issue and thanks for your help.