Rest API with same HTTP status code, different error responses for one endpoint - spring-boot

Question

We are developing our microservices using Spring Boot and OpenAPI.
Each endpoint could possibly return many business exceptions (an errorCode) and their HTTP Status Codes are all the same (say 400).
Below is a pseudo code of one of the endpoints:
#RestController
#RequestMapping("/services")
public interface MyRestController {
#PostMapping("/service1")
HttpResponse executeService(HttpRequest request)
throws FirstBusinessException, SecondBusinessException;
}
And one of the following HTTP Responses would be returned, depending on the exception which occurred:
{
"errorCode": "FirstBusinessException",
"message": "A simple message for FirstBusinessException",
"errorParams": {
"key1": "value1",
"key2": "value2"
}
}
{
"errorCode": "SecondBusinessException",
"message": "A simple message for SecondBusinessException",
"errorParams": {
"key1": "value1",
"key2": "value2"
}
}
Status Code in both of the HTTP Header Responses are 400
We want to present it in our OpenAPI documentation, as it is important to us to tell our clients about each possible error of each endpoint.
Currently our workaround solution is documenting a list of all possible exceptions of the endpoint in its description.
Now I have following questions:
Is there any better (more standard) solution to this workaround?
(I would appreciate if you could demonstrate it with springdoc-openapi way of doing it)
I've also seen anyOf/oneOf feature that has been added since OpenAPI V3, but it requires different schemas. Should we really use different schemas for our exceptions (Instead of having a single one with for example errorCode, message, and errorParam fields, like above) ?

Answer 1

I believe what you are looking for is Spring's #ControllerAdvice. Something like this
#ControllerAdvice
public RestExceptionHandler {
#ExceptionHandler(FirstBusinessException.class)
public HttpResponse handleFirstBusinessException(FirstBusinessException ex, HttpRequest request) {
... do logic and return response
}
#ExceptionHandler(SecondBusinessException.class)
public HttpResponse handleSecondBusinessException(SecondBusinessException ex, HttpRequest request) {
... do logic and return response
}
}
This allows you to return the same HttpStatus for both errors, but a custom error message and/or response entity for each.
Then, in your openApi documentation, you can set it up like this
'400':
description: You have made an invalid request
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/ExceptionOne"
- $ref: "#/components/schemas/ExceptionTwo"
examples:
Exception One:
value:
Exception: invalid Id Provided
Provided ID: My ID 1
Message: don't do that
Exception two:
value:
Exception: incomplete request
message: missing one or more fields within your json request
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
When you provide multiple examples, this provides a drop down in your ui (I'm using swagger here) to show your users what the various responses may look like.
You can use these responses and their titles to better explain. For example, instead of calling it ExceptionOne you could call it Missing ID, or Duplicate ID.
If this doesn't work for you, another option is to make use of markdown syntax in your description to make your description more robust. For example:
description: |
# You have made an invalid request
## Exceptions contained here include:
1. Bad ID
2. Your json failed validation
3. You can't follow instructions
| exception | fix |
| --- | --- |
|badId | fix ID|
| failed validation | read validation error message |
| can't follow instructions | read better |
---
If these are in error, contact us:</br>
**phone**: 555-555-5555 </br>
**email**: us#help.com
Have a nice day.
will render as