Swagger Annotations

Typescript-generator is able to use Swagger annotations for following purposes:

1. JAX-RS method return types
2. Documentation

It is not a typescript-generator goal to support all Swagger annotations.

JAX-RS method return types

When generating client for JAX-RS application typescript-generator needs to know return types of service operations. These methods can either declare particular return type but they can also return Response. In this case typescript-generator can only use any as return type.

Here is example method with Response return type:

@POST
@Path("something")
public Response createSomething(Something something) {
    if (!ok) {
        throw new WebApplicationException(Response
                .status(Response.Status.BAD_REQUEST)
                .entity(new BadRequestDetails("Wrong input"))
                .build());
    }
    Something newSomething = createSomething();
    return Response
            .created(location)
            .entity(newSomething)
            .build();
}

but if you annotate this method with Swagger annotations as follows:

@ApiOperation(value = "Creates something.", response = Something.class)
@ApiResponses({
    @ApiResponse(code = 400, message = "Bad Request", response = BadRequestDetails.class),
})
@POST
@Path("something")
public Response createSomething(Something something) {
    ...
}

typescript-generator is able to detect desired return type (Something) and also generates declarations for other possible response classes (BadRequestDetails in this example).

Documentation

Typescript-generator can take Javadoc comments and generate JSDoc comments. But this is relatively complex setup especially when typescript-generator is not run in the same module as Java source code resides.

So it is now possible to use Swagger annotations for documentation purposes. Typescript-generator uses following annotation elements:

• @ApiModel.description
• @ApiModelProperty.value
• @ApiOperation.value
• @ApiResponse.code and @ApiResponse.message