java - 有没有办法通过swagger注释为不同端点资源使用的模型类编写不同的文档？

Question

我使用的是 Swagger 2.0.6 版本和 JAX-WS-RS 2.0.1。

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

我的任务是，我需要为每个端点编写不同的文档。我的问题是，如果我对模型类中的描述进行更改，新的描述将在所有 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 Bad request 错误

Cannot deserialize instance of java.util.ArrayList out of START_OBJECT token

请问有人知道如何通过重新设计我的 java 类或使用一些 swagger 注释来完成我的任务吗？

更多信息:

这是我的终点资源:

@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 中，使用泛型。与 public class PatchOperations 一样，列表将是 private List operationList；那么 DBRolePatch 将会像这样改变: public class DBRolePatch extends PatchOperations{ 。 。 。 } 并删除@Schema注释