Swagger Annotation

1. @Tag

@Tag(name="tag_name", description="tag_description")

Tag 에 설정된 name이 같은 것끼리 하나의 api 그룹으로 묶음.

주로 Controller 영역에 설정함

 

 

 

2. @Schema

@Schema(description="한글이름", defaultValue="기본값", allowableValues="")

모델에 대한 정보를 작성하는 곳이다.

 

 

 

3. @Operation

@Operation(summary="api에 대한 간략한 설명", description="api에 대한 상세 설명", response="api response list", parameter="api parameter list")

api 동작에 대한 명세를 작성하기 위해 Controller 메소드에 설정하는 곳이다.

 

• summary : swagger UI가 접혀있을 때, 간단히 확인할 수 있는 정보
• description : 필요에 따라 상세 정보를 표기하고자 할 때 추가

 

 

 

4. @ApiResponse

@ApiResponse(responseCode="HTTP status code", description="response에 대한 설명", content="response payload 구조")

단순히, 200 코드만 제공할게 아니라면 아래와 같이 적어주면 된다.

 

• 예제

ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "유저 조회 성공", content = @Content(schema = @Schema(implementation = users.class))),
        @ApiResponse(responseCode = "404", description = "존재하지 않는 유저 조회", content = @Content(schema = @Schema(implementation = users.class))) })
@Operation(summary = "유저 조회", description = "id를 이용하여 유저를 조회합니다.")
@GetMapping("/users/{id}")
public Users findById(@PathVariable Long id) {
    return userService.findById(id);
}

 

 

 

5. @Parameter

@Parameter(name="파라미터 이름", description="파라미터 설명", in="파라미터 위치")

• @ApiResponse 처럼 parameter 리스트를 담아 API 설정
• @Operation 처럼 parameter 요소에 설정 가능

쉽게 말해, api 파라미터 리스트를 보여준다.

 

예제:

    @Operation(description = "로그인")
    @PostMapping(value = "/signin")
    public ResponseEntity<UserResponse> signIn(@Parameter @RequestBody UserRequest userRequest) {
        return ResponseEntity.ok(userService.signIn(userRequest));
    }

만약, 해당 파라미터를 API 문서에 보여주고 싶지 않은 경우, @Parameter(hidden=true) 설정을 해주면 됨