Swagger 3.x 어노테이션 정리

API 그룹 설정 : @Tag

• Target : ANNOTATION_TYPE, METHOD, TYPE
• name : 태그의 이름
• description : 태그에 대한 설명

Tag에 설정된 name 이 같은 것끼리 하나의 api 그룹으로 묶는다. Controller나 Controller의 메서드 영역에 설정한다.

@Tag(name = "posts", description = "게시물 API")
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/post")
public class PostApiController {
...
}

특정 미디어 타입, 미디어 타입 목록 설명 : @Content

OpenAPI 3.0 스펙에서 특정 미디어 타입 또는 미디어 타입의 목록을 설명하는 데 쓰인다. 이
어노테이션을 통해 요청 바디, 응답 바디의 미디어 타입 및 스키마 정보를 정의할 수 있다.

@ApiResponse(responseCode = "200", description = "Successful operation",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = MyResponseObject.class)
    )
)
public ResponseEntity<MyResponseObject> response() { ... }

API Schema 설정 : @Schema

• Target : ANNOTATION_TYPE, FIELD, METHOD, PARAMETER, TYPE
• description : 설명
• defaultValue : 기본값
• allwableValues

Schema를 이용하여 Model에 대한 정보를 작성할 수 있다. 각 필드값들에 대한 설명이나 기본값, 허용가능한 값 등 api 문서를 더 상세히 기술하는 데 사용된다.

@RestController
@RequiredArgsConstructor
@Validated
@RequestMapping("/member")
public class MemberRestController {
		@GetMapping("/{memberId}/ongoing-mission")
    @Operation(
            summary = "해당 멤버가 진행 중인 미션 목록 조회 API",
            description = "특정 멤버가 진행 중인 미션 목록을 조회하는 API이며, 페이징을 포함합니다."
                    + "query string으로 page 번호를 주세요(size는 선택, 기본 10)"
    )
    @ApiResponses({
            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "COMMON200", description = "OK, 성공"),
            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "AUTH003", description = "access 토큰을 주세요!",
                    content = @Content(schema = @Schema(implementation = ApiResponse.class))),
            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "AUTH004", description = "acess 토큰 만료",
                    content = @Content(schema = @Schema(implementation = ApiResponse.class))),
            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "AUTH006", description = "acess 토큰 모양이 이상함",
                    content = @Content(schema = @Schema(implementation = ApiResponse.class))),
            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "MEMBER4001", description = "해당 멤버가 존재하지 않음",
                    content = @Content(schema = @Schema(implementation = ApiResponse.class))),
            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "PAGE4001", description = "유효하지 않은 페이지 번호(1 미만)",
                    content = @Content(schema = @Schema(implementation = ApiResponse.class)))
    })
    @Parameters({
            @Parameter(name = "memberId", description = "멤버의 ID, path variable"),
            @Parameter(name = "page", description = "페이지 번호, 1이상이어야 함, query string"),
            @Parameter(name = "size", description = "(선택적) 페이지당 컨텐츠 개수, 기본 10, query string")
    })
    public ApiResponse<PageResponseDto<OngoingMissionResponseDto>>
    getOngoingMissions(@PathVariable @Positive Long memberId,
                       @RequestParam(name = "page") @CheckPage Integer page,
                       @RequestParam(name = "size", required = false) Integer size) {
        PageRequest pageRequest = PageDtoConverter.toPageRequest(page, size);
        Page<MemberMission> ongoingMissions = memberQueryService.getOngoingMissions(memberId, pageRequest);
        PageResponseDto<OngoingMissionResponseDto> response =
                MemberConverter.ongoingMissionPageResponseDto(ongoingMissions);
        return ApiResponse.onSuccess(response);
    }
}

API 상세 정보 기술 : @Operation

2.x 버전의 @ApiOperation 과 유사한 기능을 하며 API 동작에 대한 명세를 작성하기 위해 Controller 메서드에 설정한다. Swagger UI에서 세부 내용을 펼치지 않았을 때 간략히 확인할 수 있는 정보는 summary에 저장하고, 필요에 따라 상세 정보를 표기하고자 한다면 description에 설명을 추가하면 된다.

• Target: ANNOTATION_TYPE, METHOD
• summary : API에 대한 간략 설명
• description : API에 대한 상세 설명

@Operation(
        summary = "해당 멤버가 진행 중인 미션 목록 조회 API",
        description = "특정 멤버가 진행 중인 미션 목록을 조회하는 API이며, 페이징을 포함합니다."
                + "query string으로 page 번호를 주세요(size는 선택, 기본 10)"
)
...
public ApiResponse<PageResponseDto<OngoingMissionResponseDto>>
    getOngoingMissions(@PathVariable @Positive Long memberId,
                       @RequestParam(name = "page") @CheckPage Integer page,
                       @RequestParam(name = "size", required = false) Integer size) { ... }

API Response 정보 작성 : @ApiResponse

• Target: ANNOTATION_TYPE, METHOD, TYPE
• responseCode: http 상태코드
• description: response에 대한 설명
• content: Response payload 구조
  • schema: payload에서 이용하는 Schema
    • hidden: Schema 숨김 여부
    • implementation: Schema 대상 클래스

응답 결과에 따른 response 구조를 미리 확인할 수 있게 해준다. 지정하지 않을 경우 상태코드 200과 비어있는 응답 바디로 표기된다. @ApiResponses 를 활용하여 복수 개를 한 번에 작성할 수 있다.

@ApiResponses({
        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "COMMON200", description = "OK, 성공"),
        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "AUTH003", description = "access 토큰을 주세요!",
                content = @Content(schema = @Schema(implementation = ApiResponse.class))),
        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "AUTH004", description = "acess 토큰 만료",
                content = @Content(schema = @Schema(implementation = ApiResponse.class))),
        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "AUTH006", description = "acess 토큰 모양이 이상함",
                content = @Content(schema = @Schema(implementation = ApiResponse.class))),
        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "MEMBER4001", description = "해당 멤버가 존재하지 않음",
                content = @Content(schema = @Schema(implementation = ApiResponse.class))),
        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "PAGE4001", description = "유효하지 않은 페이지 번호(1 미만)",
                content = @Content(schema = @Schema(implementation = ApiResponse.class)))
})

@Operation 의 responses 에 작성할 수도 있다.

API Parameter 정보 작성 : @Parameter

Target: ANNOTATION_TYPE, FIELD, METHOD, PARAMETER

• name: 파라미터 이름
• description: 파라미터 설명
• in: 파라미터 위치
  • query, header, path, cookie

앞선 @ApiResponse 경우와 마찬가지로 @Parameters 를 이용하여 복수 개를 한 번에 작성하거나 @Operation 의 parameters 에 설정할 수도 있다.

유의할 점은 파라미터 설정시 어떤 파라미터에 대한 설정인 지 알 수 있도록 반드시 name 을 설정해주어야 한다.

참고

• spring-rest-openapi-doc