How to annotate Play 2 webapp model for swagger?

Question

I'm an android/java developer new to Play2 framework. I'm trying to generate documentation to my RESTful API with swagger.

I've managed to include swagger into my Play2 webapp and generate simple api-docs.json. The only part I am missing is model description. I have User controller and User model in /controllers and /models accordingly.

@Api(value = "/user", listingPath = "/api-docs.{format}/user", description = "User registration and authorisation")
public class User extends Controller {

    @POST
    @ApiOperation(value = "Create user", notes = "Used to register new user.")
    @ApiParamsImplicit(@ApiParamImplicit(name = "body", value = "Created user object", required = true, dataType = "User", paramType = "body"))
    @BodyParser.Of(BodyParser.Json.class)
    public static Result createUser() {
        JsonNode json = request().body().asJson();
        ObjectNode result = Json.newObject();
        JsonNode body = json.findPath("body");
        if(body.isMissingNode()) {
            result.put("status", "KO");
            result.put("message", "Missing parameter [body]");
            return badRequest(result);
        }

        JsonNode name = body.get("name");

        if(name == null) {
            result.put("status", "KO");
            result.put("message", "Missing parameter [body.name]");
            return badRequest(result);
        }

        result.put("status", "OK");
        result.put("message", "Hello " + name.getTextValue());
        return ok(result);
    }

}

I've tried to annotate model exactly as in an example

@XmlRootElement(name = "User")
public class User {
    public String name;

    @XmlElement(name = "name")
    public String getName() {
        return name;
    }
}

The result is:

{
    apiVersion: "beta",
    swaggerVersion: "1.1",
    basePath: "http://localhost:9000",
    resourcePath: "/user",
    apis: [
        {
            path: "/user",
            description: "User registration and authorisation",
                operations: [
                {
                    httpMethod: "POST",
                    summary: "Create user",
                    notes: "Used to register new user.",
                    responseClass: "void",
                    nickname: "createUser",
                    parameters: [
                        {
                        name: "body",
                        description: "Created user object",
                        paramType: "body",
                        required: true,
                        allowMultiple: false,
                        dataType: "User"
                        }
                    ]
                }
            ]
        }
    ]
}

Any ideas ?

Answer 1

I've found the answer myself. It appears that swagger acknowledges a model when it is being used as a return value, ie responseClass:

@ApiOperation(  value = "Find quiz by ID",
        notes = "Returns a quiz with given ID",
        responseClass = "models.Quiz" )
@ApiErrors(     value = {
        @ApiError(code = 400, reason = "Invalid ID supplied"),
        @ApiError(code = 404, reason = "Quiz not found") })
public static Result getQuizById(
        @ApiParam(value = "ID of question that needs to be fetched", required = true) @PathParam("quizId")
        String quizId) {

    ObjectNode result = Json.newObject();
    return ok(result);
}

Simply adding method like this makes corresponding model appear in api-docs.json.