[Spring Boot] Swagger 적용하기1 - controller & response

 

사용할 Annotation

Swagger 2.X Annotations

@Operation	특정 경로에 대한 작업 또는 일반적으로 HTTP 메서드를 설명
@ApiResponse	작업의 응답
@Tag	작업 또는 OpenAPI 정의 대한 태그
@Schema	입력 및 출력 데이터의 정의를 허용
@Content	특정 미디어의 유형에 대한 스키마 및 예제를 제공

 

API 설명 추가

@Tag(name = "Commnet", description = "댓글 관련 api")
@RestController
@RequestMapping("/comment")
@RequiredArgsConstructor
public class CommentController {

    private final CommentService commentService;
    
    @Operation(summary = "댓글 작성", description = "댓글 작성 메서드 입니다.")
    @PostMapping("/{post_id}")
    public ResponseEntity<? extends BasicResponse> commentCreate(@Schema(hidden = true) @CurrentUser Member member, @PathVariable("post_id") Long postId, @RequestBody @Valid CommentRequestDto commentRequestDto) {
        commentService.createComment(member, postId, commentRequestDto.getContent());

        return ResponseEntity.ok().body(new SingleResponse("댓글 작성 완료"));
    }
 }

• @Tag
  • Controller에 적용 description을 통해서 설명 가능
• @Operation
  • method에 적용
  • summary =  간단한 설명, description = 자세한 설명

실행결과

response 설명 추가

    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "댓글 작성 완료", content = @Content(schema = @Schema(implementation = SingleResponse.class))),
            @ApiResponse(responseCode = "400", description = "HTTP_REQUEST_ERROR", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
            @ApiResponse(responseCode = "400", description = "UNEXPECTED_ERROR", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
            @ApiResponse(responseCode = "400", description = "VALID_ERROR", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
            @ApiResponse(responseCode = "400", description = "존재하지 않는 게시글입니다", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
    })
    @Operation(summary = "댓글 작성", description = "댓글 작성 메서드 입니다.")
    @PostMapping("/{post_id}")
    public ResponseEntity<? extends BasicResponse> commentCreate(@Schema(hidden = true) @CurrentUser Member member, @PathVariable("post_id") Long postId, @RequestBody @Valid CommentRequestDto commentRequestDto) {
        commentService.createComment(member, postId, commentRequestDto.getContent());

        return ResponseEntity.ok().body(new SingleResponse("댓글 작성 완료"));
    }

• @ApiResponse
  • method의 Response에 대한 설명을 작성
  • 복수개를 사용하고 싶다면 @ApiRespones 사용
• Content
  • response payload 구조
• Schema: payload에서 이용하는 Schema
  • implementation: Schema 대상 클래스

response shcema 설정

@Getter
@Setter
@Schema(description = "성공(Single) 형식 Response")
public class SingleResponse extends BasicResponse {

    @Schema(description = "응답 코드", defaultValue = "200")
    private int code;
    @Schema(description = "응답 메시지")
    private String message;

    public SingleResponse(String message) {
        this.code = 200;
        this.message = message;
    }

    public SingleResponse(int code, String message) {
        this.code = code;
        this.message = message;
    }
}

 

!문제! - 상태코드가 같으면 1개만 결과가 나옴

• 위의 코드에서 400에 대한 ErrorResponse는 4개인데 결과는 1개만 나온다.

해결방법

• 줄바꿈은 통해 여러 message 담아서 보여주는 방법
• 줄바꿈 <br> 사용

    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "댓글 작성 완료", content = @Content(schema = @Schema(implementation = SingleResponse.class))),
            @ApiResponse(responseCode = "400", description = "존재하지 않는 게시글입니다" + "<br>HTTP_REQUEST_ERROR" + "<br>UNEXPECTED_ERROR"
                    + "<br>VALID_ERROR" + "<br>HTTP_REQUEST_ERROR" + "<br>Bad Request" + "<br>다시 로그인해주세요",
                    content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
    })

줄바꿈 추가 후 실행결과

• 동일한 상태코드에 대해 여러 message가 나온다.

 

response 중복 제거 - 커스텀 어노테이션

@ApiResponse를 사용하여 직접적으로 controller에 작성하면 동일한 response에 대해서 중복적인 작성이 필요해진다. 중복을 제거하기 위해서 response를 모아두는 커스텀 어노테이션을 만들어서 중복되는 코드를 최소화할 수 있다.

 

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@Documented
@ApiResponses({
        @ApiResponse(
                responseCode = "403",
                description = "USER_NOT_FOUND",
                content = @Content(schema = @Schema(implementation = ErrorResponse.class))
        ),
        @ApiResponse(
                responseCode = "500",
                description = "Internal Server Error",
                content = @Content(schema = @Schema(implementation = ErrorResponse.class))
        )
}
)
public @interface ApiDocumentGlobalResponse {
}

 

meta-annotaition이란?
다른 annotation 에서도 사용되는 annotation의 경우를 말하여 custom-annotation을 생성할 때 주로 사용된다.

• @Retention: 어노테이션의 라이프 사이클
  • RetentionPolicy.RUNTIME: 어노테이션을 런타임시에까지 사용할 수 있다.
• @Target: Java compiler가 annotation 이 어디에 적용될지 결정하기 위해 사용
  • ElementType.TYPE: 타입 선언 시 사용
  • ElementType.METHOD:  메서드 선언 시 사용

 

controller에 적용

 

- response가 잘 나오는 것을 확인할 수 있다.