[Spring] Swagger 공통 응답 예시 커스터마이징

SuccessResponse 를 @RestControllerAdvice 를 이용해 전역 처리 중이며
Swagger Example 커스터마이징을 하고 싶은 경우
이 글을 읽어주시면 도움이 될 것 입니다.

 

들어가며

Swagger 를 사용중이며, @RestControllerAdvice 를 사용해 전역 응답을 설정중인 경우
Swagger 응답 예시에서 wrapping 시켜주는 객체가 나타나지 않는다.

최근에는 springfox 공식 업데이트가 멈췄고 springdocs 를 많이 사용중이다.
springfox 같은 경우 기본 설정으로 제네릭 클래스를 응답으로 선택할 수 있는데
springdocs 에서는 이를 지원해주지 않아 다른 방법을 사용해야 한다.

 

SuccessResponseAdvice 예시

@Getter
@NoArgsConstructor
public class SuccessResponse<T> {

    private final boolean success = true;
    private final LocalDateTime timeStamp = LocalDateTime.now();
    private int status;
    private T data;

    public SuccessResponse(T data) {
        this.status = 200;
        this.data = data;
    }

    public SuccessResponse(T data, int status) {
        this.status = status;
        this.data = data;
    }
}

@RestControllerAdvice(basePackages = "kr.co.swagger")
public class SuccessResponseAdvice implements ResponseBodyAdvice<Object> {
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

    @Override
    public Object beforeBodyWrite(
            Object body,
            MethodParameter returnType,
            MediaType selectedContentType,
            Class<? extends HttpMessageConverter<?>> selectedConverterType,
            ServerHttpRequest request,
            ServerHttpResponse response) {
        final HttpServletResponse servletResponse =
                ((ServletServerHttpResponse) response).getServletResponse();

        int status = servletResponse.getStatus();
        final HttpStatus resolve = HttpStatus.resolve(status);

        if (resolve == null) {
            return body;
        }

        if (resolve.is2xxSuccessful()) {
            return new SuccessResponse<>(body, status);
        }

        return body;
    }
}

 

예시 응답

실제 응답

이럴 경우 swagger 상에서 설정을 바꿔줘서 기본 예시를 wrapping 할 수 있다.

 

Swagger 동작 원리

{host}/v3/api-docs 로 접속할 경우 아래와 같이 swagger-ui 로 변환되기 이전의 JSON 데이터가 노출된다.
이를 바탕으로 스웨거는 화면에 API 문서를 띄우게 된다.

즉 이 JSON 데이터를 설정해준다면 스웨거가 그리는 화면을 수정할 수 있다는 것이다.

 

Swagger Customizer

스웨거에서는 customizer 라는 함수형 인터페이스를 제공하는데
이를 빈으로 등록하게 될 경우 커스터마이징을 할 수 있다

이 중에서 컨트롤러 메소드를 처리하는 OperationCustomizer 를 사용할 것이다.

@FunctionalInterface
public interface OperationCustomizer {
    Operation customize(Operation operation, HandlerMethod handlerMethod);
}

 

공통 응답 랩핑 처리

@Configuration
public class SwaggerConfig {
    ...

    @Bean
    public OperationCustomizer operationCustomizer() {
        return (operation, handlerMethod) -> {
            this.addResponseBodyWrapperSchemaExample(operation);
            return operation;
        };
    }

    private void addResponseBodyWrapperSchemaExample(Operation operation) {
        final Content content = operation.getResponses().get("200").getContent();
        if (content != null) {
            content.forEach((mediaTypeKey, mediaType) -> {
                Schema<?> originalSchema = mediaType.getSchema();
                Schema<?> wrappedSchema = wrapSchema(originalSchema);
                mediaType.setSchema(wrappedSchema);
            });
        }
    }

    private Schema<?> wrapSchema(Schema<?> originalSchema) {
        final Schema<?> wrapperSchema = new Schema<>();

        wrapperSchema.addProperty("success", new Schema<>().type("boolean").example(true));
        wrapperSchema.addProperty("timeStamp", new Schema<>().type("string").format("date-time").example(
                LocalDateTime.now().toString()));
        wrapperSchema.addProperty("status", new Schema<>().type("integer").example(200));
        wrapperSchema.addProperty("data", originalSchema);

        return wrapperSchema;
    }
}

operation 의 getResponses() 를 통해 예시 응답 리스트를 꺼내고 그 중에서 200 성공 응답에 대해 가져온다.
JSON 에서 각 컨트롤러 메소드의 예시는 응답 코드 쌍으로 그룹핑된다.

그 후 내부에서는 각 mediaType 별로 그룹핑되어 있는데, 이 중에서 Schema 를 꺼내면 원본 예시가 나오게 된다.
이를 새로운 응답으로 랩핑해주면 원하는 결과가 나올 것이다.

 

기존 JSON

...        
        "/user": {
            "get": {
                "tags": [
                    "사용자 API"
                ],
                "summary": "사용자 정보 조회",
                "description": "사용자 정보를 조회합니다.",
                "operationId": "getUser",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json;charset=UTF-8": {
                                "schema": {
                                    "$ref": "#/components/schemas/UserResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
...

새로운 JSON

...
			"/user": {
            "get": {
                "tags": [
                    "사용자 API"
                ],
                "summary": "사용자 정보 조회",
                "description": "사용자 정보를 조회합니다.",
                "operationId": "getUser",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json;charset=UTF-8": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "timeStamp": {
                                            "type": "string",
                                            "format": "date-time",
                                            "example": "2024-03-17T18:30:50.334396"
                                        },
                                        "status": {
                                            "type": "integer",
                                            "example": 200
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/UserResponse"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
...

결과

각 스키마에 property 가 지정되며 응답이 성공적으로 wrapping 되었다.
다만 각 필드를 삽입하는 과정에서 텍스트를 하드코딩하게 되는 문제가 있는데 리플렉션으로 해결해보았다.

 

@Configuration
public class SwaggerConfig {
    ...
    
    @Bean
    public OperationCustomizer operationCustomizer() {
        return (operation, handlerMethod) -> {
            this.addResponseBodyWrapperSchemaExample(operation, SuccessResponse.class, "data");
            return operation;
        };
    }
    
    private void addResponseBodyWrapperSchemaExample(Operation operation, Class<?> type, String wrapFieldName) {
        final Content content = operation.getResponses().get("200").getContent();
        if (content != null) {
            content.keySet()
                    .forEach(mediaTypeKey -> {
                        final MediaType mediaType = content.get(mediaTypeKey);
                        mediaType.schema(wrapSchema(mediaType.getSchema(), type, wrapFieldName));
                    });
        }
    }
    
    @SneakyThrows
    private <T> Schema<T> wrapSchema(Schema<?> originalSchema, Class<T> type, String wrapFieldName) {
        final Schema<T> wrapperSchema = new Schema<>();
        final T instance = type.getDeclaredConstructor().newInstance();
        
        for (Field field : type.getDeclaredFields()) {
            field.setAccessible(true);
            wrapperSchema.addProperty(field.getName(), new Schema<>().example(field.get(instance)));
            field.setAccessible(false);
        }
        wrapperSchema.addProperty(wrapFieldName, originalSchema);
        return wrapperSchema;
    }
}

이렇게 되면 SuccessResponse 필드 코드가 바뀌었을 때에도 조치가 가능하다.
이 부분은 최초 Swagger 로딩시에만 리플렉션이 동작하고 이후에는 캐싱되기 때문에 어느정도 감수할만 하다고 생각해서 적용해보았다.

스웨거 커스터마이징에 익숙해진다면 더 좋은 방법이 있을 수도 있을 것 같다.

 

마치며

스웨거 응답을 커스터마이징하여 API 문서의 공통 응답을 변경하는 방법을 알아보았다.
이외에도 예외 처리에 대한 문서 자동화, 복잡한 처리 등이 가능하니 잘 찾아본다면 더 깔끔하고 정확한 스웨거 문서를 작성할 수 있겠다.