[Spring] Swagger 어노테이션 정리

-이전 게시물 

https://gotopm.tistory.com/80

[Spring] Swagger

 

---

 

1.Tag 어노테이션

:API 그룹을 지정할 때 사용한다. 주로 컨트롤러 클래스 위에 붙여서, Swagger UI에서 API들을 카테고리별로 구분하는 데 사용한다.

 

2.Operation 어노테이션

Tag가 컨트롤러 '클래스' 위에 붙여 해당 API그룹을 설명한다면, Operation 어노테이션은 컨트롤러에 있는 메서드 위에 붙여 해당 API가 무엇을 하는지 설명한다.

 

아래 코드를 보면 UserController 클래스 위에 Tag어노테이션을,  로그인 메서드 위에만 Operation어노테이션을 사용한 것을 확인할 수 있다.

@Tag(name="유저", description = "유저 관련 API 입니다.")
@RestController
@RequestMapping("/user")
public class UserController {
    private final UserService userService;
    private final GoogleService googleService;

    public UserController(UserService userService, GoogleService googleService) {
        this.userService = userService;
        this.googleService = googleService;
    }

    //  1.회원가입
    @PostMapping("/create")
    public ResponseEntity<?> userCreate(@RequestBody UserCreateReqDto dto){
        userService.userCreate(dto);
        return new ResponseEntity<>(new CommonDto(HttpStatus.CREATED.value(),"success","success"),HttpStatus.CREATED);
    }

//    2.로그인
    @Operation(
            summary = "로그인",
            description = "loginId와 password를 받는 DTO를 프론트 단에 받아 로그인을 처리합니다."
    )
    @PostMapping("/login")
    public ResponseEntity<?> userLogin(@RequestBody UserLoginReqDto dto){
        Map<String,Object>loginInfo = userService.userLogin(dto);
        return new ResponseEntity<>(new CommonDto(HttpStatus.OK.value(),"login success",loginInfo),HttpStatus.OK);
    }

 

그러면 이렇게 원래 UserController라고 적혀있던 부분이 유저- 유저 관련 API입니다 라는 글로,

로그인 API 옆에 내가 summary로 적힌 부분 그 아래로 description 부분이 나타난다.

 

스웨거는 @RestController 어노테이션이 붙은 컨트롤러 클래스를 자동인식하고 API를 화면에 띄우는 것과 동시에
해당 클래스에 있는 @RequestBody 어노테이션이 붙은 DTO를 인식해서 화면에 나타내주기도 한다.

그런 DTO에 대한 설명을 달 수 있는 어노테이션이 Schema 어노테이션이다.

 

3.Schema 어노테이션

DTO 클래스나 필드에 붙여서 각 데이터의 의미(description), 예시(example), 필수여부(required = true) 등을 명시할 수 있다.

아래 코드를 보면 DTO클래스 위에다 그리고 각 필드마다 Schema 어노테이션을 사용해보았다.

@AllArgsConstructor
@NoArgsConstructor
@Data
@Builder
@Schema(description = "회원가입 요청 DTO")
public class UserCreateReqDto {
    @Schema(description = "로그인 아이디", example = "samrok")
    private String loginId;
    @Schema(description = "비밀번호", example = "12341234")
    private String password;
    @NotBlank
    @Schema(description = "이름", example = "김진영")
    private String name;
    @NotBlank
    @Size(min = 2, max =8, message = "닉네임은 최소 2자 이상 8자 이하로 입력 가능합니다.")
    @Schema(description = "닉네임", example = "삼록이")
    private String nickname;
    @NotBlank
    @Size(min=8)
    @Schema(description = "생일", example = "19940818")
    private String birthday;
    @Schema(description = "회사명", example = "스튜디오타이거")
    private String companyName;
    @Schema(description = "직책고유ID", example = "2")
    private Long jobRoleId;

 

그러면 아래처럼 UserCreateReqDto만 설명과 예시가 붙어있는게 보인다.