Swagger 어노테이션 간소화

[Choi-JJunho]

Slack에서 발안된 논의입니다.

현재 저희가 Swagger 어노테이션을 다음과 같이 지정해주고 있습니다.

@ApiResponses(
    value = {
        @ApiResponse(responseCode = "200"),
        @ApiResponse(responseCode = "401", content = @Content(schema = @Schema(hidden = true))),
        @ApiResponse(responseCode = "403", content = @Content(schema = @Schema(hidden = true))),
        @ApiResponse(responseCode = "404", content = @Content(schema = @Schema(hidden = true)))
    }
)
@Operation(summary = "학기 정보 조회")
@GetMapping("/semesters")
ResponseEntity<List<SemesterResponse>> getSemesters();

401, 403, 404 같은걸 매번 지정해주는 작업이 꽤나 반복적이고 불필요한 작업으로 다가옵니다.
이를 간소화 시킬 수 있는 방안은 없을까요?

[Choi-JJunho]

코드를 공통으로 묶으면 좋겠다는 생각이 들어요

권한이 필요한 API가 있고 그렇지 않은 API가 있기도해서 전역적으로 401, 403, 404를 지정하기에는 애매한 감이 들기도해서 권한을 선택적으로 정할 수 있도록 간소화하면 좋겠다는 생각도 드네요

우선은 @Document(auth=true) 같은 커스텀 어노테이션으로 분리시켜서 만드는 방향성이 떠오릅니다

[dradnats1012]

저도 커스텀 어노테이션으로 지정해주는게 좋다고 생각합니다!
어떤 식으로 필요한 응답을 지정해줄지는 생각해봐야 할 것 같습니다

[20HyeonsuLee]

어떤 요청인지(POST, PUT DELETE, GET 등)에 대한 정보도 넘겨줘서 요청에 맞게 동작하도록 작성하는것도 좋아보여요

[20HyeonsuLee]

예시) @document(auth=true, request=GET)

[songsunkook]

저도 동의합니다. 지금까지 관성적으로 해당 응답 코드들을 추가해왔는데, 이 내용을 간소화할 수 있다면 도움이 될 것 같아요!

[duehee]

저도 좋은 것 같습니다! 권한이 필요한 경우 / 권한이 필요하지 않은 경우로 에러코드를 반환하는데, 이를 축약하여 표현할 수 있다면 간결해지고 좋을 것 같습니다.