3

私は Play2 フレームワークを初めて使用する Android/Java 開発者です。swaggerを使用して RESTful API にドキュメントを生成しようとしています。

Play2 webapp に swagger を組み込み、単純な 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

私は自分で答えを見つけました。モデルが戻り値、つまりresponseClassとして使用されている場合、swagger はモデルを認識しているようです。

@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 に答える