Question

我正在使用Swagger 2.0.6版本和JAX-WS-RS 2.0.1。

我有5个不同的端点资源（其余API），它们使用相同的模型类。我已附上记录的模型模型页面的屏幕截图。

我的任务是，我需要为每个端点编写不同的文档。我的问题是，如果我对模型类中的描述进行了更改，那么新的描述将在所有5种端点资源中看到。

我的模型类是：

PatchOperations.java

public class PatchOperations {

    @Valid
    private List<PatchOperation> operationList;

    public PatchOperations() {
    }

    @Override
    public String toString() {
        return "PatchOperations{" +
            "operationList=" + operationList +
            '}';
    }

    public List<PatchOperation> getOperationList() {
        return operationList;
    }

    public void setOperationList(List<PatchOperation> operationList) {
        this.operationList = operationList;
    }
}

PatchOperation.java

public class PatchOperation {

    /**
     * {@link PatchOperator} operation to be performed
     */
    @Schema(description = "Operation to be performed", required = true)
    @JsonProperty
    @NotNull
    private PatchOperator op;

    @Schema(description = "Path to target where operation will be performed", required = true)
    @JsonProperty
    @Pattern(regexp = RegExConstants.PATCH_PATH, message = "Invalid path, the path should match regex '" + RegExConstants.PATCH_PATH + "'")
    private String path;

    @Schema(description = "Value used by operation [new value to add, new value used to replace existing value, existing value to be removed]")
    @JsonProperty
    private Object value;

    public PatchOperation() {
    }
}

我尝试通过创建2个新类来扩展PatchOperations和PatchOperation

public class DBRolePatch extends PatchOperations {

    @Override
    @Schema(implementation = DBRolePatchOperation.class)
    public List<PatchOperation> getOperationList() {
        return super.getOperationList();
    }
}


public class DBRolePatchOperation extends PatchOperation {

    @Override
    @Schema(description = "New description for Db role", example = "ADD", required = true)
    public PatchOperator getOp() {
        return super.getOp();
    }

    @Override
    @Schema(description = "New description for DBROLE", example = "/Name", required = true)
    public String getPath(){
        return super.getPath();
    }

    @Override
    @Schema(description = "New Description for DB ROLE", example = "New Project Name", required = true)
    public Object getValue(){
        return super.getValue();
    }

}

从上述设计模式的新变化中，我将覆盖所有属性的新描述并完成我的任务，但是从我的变化之上，这将构成不同的请求正文。

{
 “operationList”: {
   “op”: “ADD”,
   “path”: “/Name”,
   “value”: “Autopilot”
 }
}

原始请求正文如下：

{
 “operationList”: [
   {
     “op”: “ADD”,
     “path”: “string”,
     “value”: {}
   }
 ]
}

因此，我说的是400错误的请求错误

无法反序列化java.util.ArrayList的实例 START_OBJECT令牌

请问有人对我如何通过重新设计Java类或使用一些招摇的注解来完成任务有任何想法。

更多信息：

这是我的终点资源：

@PATCH
    @AuthenticatedSession
    @Path(“/{id}“)
    @Consumes(MediaType.APPLICATION_JSON)
    @Operation(summary = ” Update DB role.“)
    @ApiResponses(value = {
            @ApiResponse(responseCode = “201”, description = MessageConstants.CREATED),
            @ApiResponse(responseCode = “400", description = MessageConstants.BAD_REQUEST, content = @Content(schema = @Schema(implementation = RestError.class)))})
    public Response updatePartialDBRole(
            @Parameter(description = SwaggerConstants.AUTHORIZATION_TOKEN_DESC, required = true) @HeaderParam(ParamNames.SESSION_TOKEN) String authToken,
            @Parameter(description = SwaggerConstants.DBROLE_ID_DESC, required = true) @PathParam(“id”) String id,
            @Parameter(description = SwaggerConstants.PATCH_OPERATION_DESC, required = true) @Valid DBRolePatch operationList,
            @Context UriInfo uriInfo)throws RestException {
            return delegate.updatePartialDBRoleInResponse(SessionInjectionHelper.getSession(requestContext), id, operationList, uriInfo);
}

Answer 1

尽量不要在模型类中添加文档。或者，如果您这样做，则在其中添加所有端点都通用的文档。然后，在每个端点中，您可以使用一些Swagger批注来编写一些文档。试试这个：

 @ApiOperation( position = 100,
               value = "Retrieve SecurityToken authentication using BODY(String password)",
               notes = "Retrieve SecurityToken authentication using ReturnsId id and password",
               response = ResponseObjectClass.class)
 @ApiResponses(value = { @ApiResponse(code = 200, message = "Sucess"),
                         @ApiResponse(code = 422, message = "business exception"),
                         @ApiResponse(code = 500, message = "Server error") })
    public ResponseObjectClass someFunctionality(@ApiParam(value = "request", defaultValue = "an string as example showing your response") @RequestBody YourRequestBodyClass request, HttpServletResponse response)
                    throws Exception {
    return new ResponseObjectClass();
}

@ApiOperation和@ApiResponses是swagger注释，是swagger 2.0中io.swagger.annotations程序包的一部分。

更新

尝试以下操作：在PatchOperations.java中，使用泛型。像公共类PatchOperations一样，列表将是私有List operationList；然后，DBRolePatch将会像这样更改：公共类DBRolePatch扩展了PatchOperations {。。。 }，然后删除@Schema批注

是否有任何方法可以通过针对不同端点资源使用的模型类的大写注释来编写不同的文档？

1 个答案: