有什么方法可以通过对不同端点资源使用的模型 class 的 swagger 注释编写不同的文档吗？

Question

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

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

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

我的模型class是：

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 个新的 class 来扩展 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 classes 或使用一些夸张的注释来完成我的任务吗？

更多信息：

这是我的终点资源：

@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

尽量不要在模型中添加文档 class。或者，如果您这样做，请在其中添加所有端点通用的文档。然后，在每个端点中，您可以使用一些 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 注释

有什么方法可以通过对不同端点资源使用的模型 class 的 swagger 注释编写不同的文档吗？

Is there any way to write different documentation through swagger annotation for model class which used by different end point resources?

java

rest

swagger-2.0