Actualmente estoy trabajando en una base de código donde para cada respuesta de la API REST usan una clase Java como la siguiente
{ Object payload; List<Error> errors; String responseStatus; }El problema es que, cuando nos referimos a la documentación de swagger de las API REST, muestra una estructura json como la siguiente.
{ "payload":{}, "errors": [ { "errMsg":"", "errCode": "" } ], "responseStatus":"" }Por lo tanto, la respuesta tendrá una carga útil si la respuesta es exitosa, una lista de errores en caso de errores y un estado de respuesta establecido en éxito o falla, respectivamente.
EDITAR : solo quiero mencionar que no puedo cambiar la carga de respuesta a ninguna otra cosa, ya que se usa en más de 1000 API y se distribuye en diferentes servicios.
¿Hay alguna forma de mejorar al menos la documentación de Swagger, sin cambiar el objeto de respuesta en Java, porque ese barco zarpó hace mucho tiempo?
Aquí hay un ejemplo de la documentación de Swagger.
paths: /users/{id}: get: summary: Gets a user by ID. response: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' # Descriptions of common components components: responses: NotFound: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' schemas: # Schema for error response body Error: type: object properties: code: type: string message: type: string required: - code - message # Schema for the User response User: type: object properties: # Add properties for the User object # ...puedes usar ResponseEntity<? extends Response> tipo de retorno en sus métodos. de modo que si la respuesta es exitosa, ambos regresaron, así como la respuesta es un error.
public ResponseEntity<? extends ResponseDto> foo(RequestDto request){ if(success){ return new ResponseEntity<>(new SuccessResponse(Enum.SuccessResponse.getMessage,200,dto),HttpStatus.OK); } return new ResponseEntity<>(new ErrorResponse(Enum.ErrorResponse.getMessage,400),HttpStatus.BAD_REQUEST); }