Allow/Support springdoc-openapi to pick up @ResponseStatus correctly

[bwgjoseph]

Hi,

I would like to request for this library to be compatible with springdoc-openapi, to be able to allow springdoc-openapi to pick up @ResponseStatus defined in the @ExceptionHandler. If this is already supported, please direct me on how it can be configured as I wasn't able to find it in the docs.

I do have a repo that described in details what is this about, and what I hoped for - See https://github.com/bwgjoseph/error-handling-spring-boot-openapi.

TLDR; By using this library, springdoc-openapi wasn't able to pick up @ResponseStatus correctly, as I no longer need to define @ControllerAdvice and @ExceptionHandler myself which is what this library provides.

Without this library, the error code are generated correctly

With this library, the error code are not being picked up correctly by springdoc-openapi (I'm guessing). Even though @ResponseStatus is defined in the exception class.

@ResponseStatus(HttpStatus.PAYLOAD_TOO_LARGE)
public class MyBusinessException extends RuntimeException {
    public MyBusinessException(String message) {
        super(message);
    }
}

Note that 413 is missing

Thank you!

[wimdeblauwe]

That you for explaining your issue in such detail, that really helps. I personally do not use springdoc-openapi, I use Spring REST Docs as I find I can document things better without adding a bunch of annotations to my production code just for generating proper documentation.

That said, I don't think what you want is possible. The error handler in my library is a generic Exception handler, so I don't see how springdoc-openapi could know what exception is thrown from what controller method.

If you really want to use springdoc-openapi and want to have possible error status codes documented, then I think you need to use the @ApirResponse annotation like they do in their example:

@ApiResponses(value = {
			@ApiResponse(responseCode = "204", description = "User deleted"),
			@ApiResponse(responseCode = "400", description = "Invalid username supplied"),
			@ApiResponse(responseCode = "404", description = "User not found")
	})

[bwgjoseph]

That said, I don't think what you want is possible. The error handler in my library is a generic Exception handler, so I don't see how springdoc-openapi could know what exception is thrown from what controller method.

Actually, even without your library, springdoc-openapi doesn't know what exception is thrown from what controller method. Hence, it will by default add the response code to all the controller methods, across the entire project.

As mentioned in my repo, there's a way to do so, is to some kind of hint via @ControllerAdvice (like a filter)

@ControllerAdvice(basePackages = "com.bwgjoseph.error_handling_spring_boot_openapi.profile")

As such, I don't think your library needs to handle that as well. I only wanted to see if your library can even allow springdoc-openapi to pick up the hint (@ResponseStatus). Once that happens, I think there might be a way to provide some sort of customizer to filter to a particular controller methods for the exception (see https://stackoverflow.com/questions/70943125/spring-boot-openapi-restcontrolleradvice-not-limited-to-methods-throwing-the)

then I think you need to use the @ApiResponse

Yup, I'm familiar with that annotation, but I have over 300 APIs and writing all of them with the annotation will indeed help to generate the documentation correctly. I did not notice that it was not generated in the OpenApi documentation until someone highlighted it to me.

I still much prefer to use your library and let springdoc-openapi to pick up automatically, as though I'm writing the handler myself (rather the library doing it).

@ControllerAdvice
public class MyExceptionHandler {
    @ExceptionHandler(MyBusinessException.class)
    // this must be added in order for springdoc-openapi to automatically generate the response
    @ResponseStatus(HttpStatus.PAYLOAD_TOO_LARGE)
    public Error handle() {
        return new Error("1234", "null");
    }
}

Thank you