Java 对于不同端点资源使用的模型类，有没有办法通过swagger注释编写不同的文档？

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

我有不同的5个端点资源（RESTAPI），它们使用相同的模型类。我已经附上了记录在案的模特大摇大摆页面的截图

我的任务是，我需要为每个端点编写不同的文档。我的问题是，如果我在模型类中更改了描述，那么新的描述将出现在所有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;
    }
}

我尝试创建了两个新类，扩展了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”: “string”,
     “value”: {}
   }
 ]
}

因此，我得到了一个400错误的请求

无法从中反序列化

java.util.ArrayList

的实例 启动对象令牌

你能告诉别人我如何通过重新设计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);
}

---

尽量不要在模型类中添加文档。或者，如果您这样做了，请在那里添加所有端点通用的文档。然后，在每个端点中，您可以使用一些招摇过市的注释来编写一些文档。试试这个：

 @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中，使用泛型。与公共类修补操作类似，列表将是私有列表操作列表；然后DBRolePatch将如下更改：公共类DBRolePatch扩展修补操作{…}并删除@Schema注释

请查看我的问题描述。我已经添加了我的端点资源。出于某种或其他原因，我已经在使用您提到的所有注释，但我的任务无法通过在端点添加描述来实现。或者，您可以告诉我如何为单个对象的所有属性添加描述。与公共类修补操作类似，列表将是私有列表操作列表；然后DBRolePatch将如下更改：公共类DBRolePatch扩展PatchOperations{…}尝试格式化我的最后一条注释，因为它包含代码。无论如何，这只是一个解决办法，不确定它是否会奏效。实际上，您扩展类只是为了能够向每个类添加不同的文档。如果您有不同的端点，并且所有端点共享相同或相似的类，并不意味着您需要使用相同的类。也许你认为数据结构是一样的，但这可能只是巧合。我想再考虑一下您的层次结构，您的子类没有添加新功能。忘了说，也请删除子类中的架构注释。{“operationList”：{“op”：“ADD”，“path”：“/Name”，“value”：“Autopilot”}我确实按照您的建议进行了更改。但它仍在构建错误的请求机构。

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

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