3

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

我设法将 swagger 包含到我的 Play2 webapp 中并生成简单的 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);
    }

}

我试图完全按照示例注释模型

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

有任何想法吗 ？

4

1 回答 1

2

我自己找到了答案。看起来，当模型被用作返回值时，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 中。

于 2013-02-24T14:24:31.823 回答