如何为 swagger 注释 Play 2 webapp 模型？

Question

我是一名刚接触 Play2 框架的 android/java 开发人员。我正在尝试使用swagger 为我的RESTful API 生成文档。

我已设法将 swagger 包含到我的 Play2 web 应用程序中并生成简单的 api-docs.json。我唯一缺少的部分是模型描述。我在 /controllers 和 /models 中有相应的用户控制器和用户模型。

@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);
    }

}

我尝试完全按照example 中的方式注释模型

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

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

结果是：

{
    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"
                        }
                    ]
                }
            ]
        }
    ]
}

有什么想法吗？

Answer 1

我自己找到了答案。 看来，当模型被用作返回值时，swagger 会承认模型，即 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);
}

只需像这样添加方法，相应的模型就会出现在 api-docs.json 中。