Only extend defined ApiResponses with generic responses from controller advice

[m-kay]

The responses generated from a controller advice are currently added to every operation. However in some cases it is impossible to get this error/response on a certain operation. Therefore I would suggest to only add all generic responses if no @ApiResponse annotation is present on an operation. If there are @ApiResponse annotations on an operation I would only extend this config with the generated generic response so one could configure which of the generic responses are shown for which operation.

[bnasslahsen]

Hi @m-kay,

The following property will be available on v1.2.32:

springdoc.override-with-generic-response=false

It will allow you to:

• Only add all generic responses if no @ApiResponse annotation is present
• If there is an @ApiResponse annotations prensent on an operation, it will be used instead as reference

[m-kay]

Thanks @bnasslahsen

This is already helpful but not completely what I was expecting. What I meant by "enhancing" was that if there is a generic response with schema lets say for response code 400 and I have the annotation @ApiResponse(responseCode = "400", description = "BAD_REQUEST") on my operation then also add the generic response schema. Does that make sense to you?

I already had that implemented on a feature branch and was breaking quite a lot of tests, thats why I wanted to have your opinion first. Now with the configuration property this should not break the current tests. I will try to combine your change with my solution and make a PR.

[bnasslahsen]

Hi @m-kay,

I had a doubt that you also, wanted to merge the @ApiResponse from the RestController with the one from @ControllerAdvice. I just didn't want to go further, because it was going to add more complexity and wasn't sure about your requirement.
You can propose your PR and we will integrate it.

[OmarHawk]

mh, seems like it never made it into the library.

I'd like to also have such a feature, where @ControllerAdvice are scanned for corresponding status codes, so that the Schema is merged into the appropriate @ApiResponse, if no schema is defined there - so that you don't have to repeat the very same @Schema with @Content and so on all over again and again, without having too many (irrelevant) error codes in the final docs.

@bnasslahsen: Do you think it makes sense to at least open a separate issue for that?

[bnasslahsen]

@OmarHawk,

There is no need to open a separate ticket.
As suggested earlier, just submit your PR.