Есть ли способ написать различную документацию посредством аннотации swagger для класса модели, который используется различными ресурсами конечных точек?

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 новых класса, которыеextends 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, говоря:

Невозможно десериализовать экземпляр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, часть пакета io.swagger.annotations в swagger 2.0.

ОБНОВЛЕНИЕ

Попробуйте это: в PatchOperations.java используйте дженерики.Подобно общедоступному классу PatchOperations, и список будет закрытым List operationList;Тогда DBRolePatch изменится так: открытый класс DBRolePatch расширяет PatchOperations {.,,} и удалите аннотацию @Schema