Collectives™ on Stack Overflow

Find centralized, trusted content and collaborate around the technologies you use most.

Teams

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

How to DRY when using Swagger UI and the ApiResponses annotations with Java Spring endpoints?

I like Swagger because it makes your apis very user friendly. I use Swagger annotations like

On endpoints, query params, request params, request body and so on.

I like to keep my POJO classes clean and in general I try my best to follow DRY rule however, when it comes to swagger I noticed that I keep repeating myself over and over as shown below

@ApiOperation(value = "Retrieve object by id")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "OK"),
    @ApiResponse(code = 404, message = "Not Found"),
    @ApiResponse(code = 400, message = "Bad Request"),
    @ApiResponse(code = 500, message = "ISE")
public Response retrieveById(@ApiParam(value = "Some id") @PathParam("sid") int id) {       
@ApiOperation(value = "Create object")
@ApiResponses(value = {
    @ApiResponse(code = 201, message = "Created"),
    @ApiResponse(code = 404, message = "Not Found"),
    @ApiResponse(code = 400, message = "Bad Request"),
    @ApiResponse(code = 500, message = "ISE")
public Response create(@ApiParam(value = "Request body") RequestBody body) {
How to avoid repeating yourself with Swagger annotations? 
I did some Googling around and came across this github issue and some other SO questions that are not directly related to ApiResponses annotations and none of them seem to present a working solution.
Using Swagger UI 2.0  I thought let's give it a try, so I did the following 
I created a custom annotations GroupedApiResponses.. 
I annotated GroupedApiResponses.. with a group of Swagger annotations
I used the GroupedApiResponses.. annotations on top of endpoints 
Works just like before 
See below 
package com.raf.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Ok"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 400, message = "Bad Request"),
        @ApiResponse(code = 500, message = "ISE") 
public @interface GroupedApiResponsesAvecOk {
Similarly (you can group annotations as you want in one or more than one custom annotation depending on structure of your endpoints and the response messages it return)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@ApiResponses(value = {
        @ApiResponse(code = 201, message = "Created"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 400, message = "Bad Request"),
        @ApiResponse(code = 500, message = "ISE") 
public @interface GroupedApiResponsesAvecCreated {
And then I used the above @GroupedApiResponsesAvecOk on retrieveById and @GroupedApiResponsesAvecCreated on create endpoint in place of @ApiResponses and worked it just like before. 
As shown above, the ApiResponse annotations relating to 400, 404, 500 can now be reused across other endpoints. 
                Very nice. Is there anyway to provide an input to the new meta-annotation that allows the user to specify the response type for one of the @ApiResponses?
– RocketMan
                Sep 9, 2021 at 16:50
        
Thanks for contributing an answer to Stack Overflow!
Please be sure to answer the question. Provide details and share your research!
But avoid …
Asking for help, clarification, or responding to other answers.
Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.