@Schema(description = "사용자 DTO")
@Getter
@Setter
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class UserDto {
@Schema(
description = "사용자 이름",
requiredMode = Schema.RequiredMode.REQUIRED,
example = "test1"
)
private String username;
@Schema(
description = "비밀번호",
requiredMode = Schema.RequiredMode.REQUIRED,
example = "T1q2w3e4r!"
)
private String password;
public static UserDto fromEntity(User entity) {
return UserDto.builder()
.username(entity.getUsername())
.build();
}
}
// 회원가입
@Operation(
summary = "신규 사용자 회원가입",
description = "비밀번호는 8자리 이상, 대문자 & 특수문자 1개씩 필수값입니다.",
requestBody = @RequestBody( // 이 requestBody는 io.swagger.v3.oas.annotations.parameters.RequestBody 입니다.
description = "회원가입에 필요한 사용자 정보",
required = true,
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = UserDto.class),
examples = {
@ExampleObject(
name = "회원가입 요청 예시",
summary = "회원가입 성공 케이스",
value = "{\"username\": \"newuser123\", \"password\": \"NewPassword1!\"}",
description = "유효한 사용자명과 비밀번호로 회원가입 요청"
)
// 필요하다면 다른 예시 추가 가능 (예: 비밀번호 규칙 위반 등)
}
)
)
)
@PostMapping("/join")
public UserDto signUp(@org.springframework.web.bind.annotation.RequestBody UserDto dto) { // 스프링 부트의 @RequestBody
return authService.signUp(dto);
}
// 회원탈퇴
@Operation(
summary = "사용자 회원탈퇴",
description = "회원 탈퇴를 위한 비밀번호를 입력합니다. (사용자명은 토큰 등으로 자동 인식된다고 가정)",
requestBody = @RequestBody( // 이 requestBody는 io.swagger.v3.oas.annotations.parameters.RequestBody 입니다.
description = "회원탈퇴 시 비밀번호 확인",
required = true,
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = UserDto.class), // 동일 DTO 사용
examples = {
@ExampleObject(
name = "회원탈퇴 요청 예시",
summary = "회원탈퇴 비밀번호",
value = "{\"password\": \"T1q2w3e4r!\"}",
description = "회원 탈퇴 시 본인 확인을 위한 비밀번호"
)
}
)
)
)
@DeleteMapping("/delete")
public ResponseEntity<String> deleteUser(
@org.springframework.web.bind.annotation.RequestBody UserDto dto // 스프링 부트의 @RequestBody
) {
authService.deleteUser(dto.getPassword());
return ResponseEntity.ok("User deletion is success");
}
}
io.swagger.v3.oas.annotations.parameters.RequestBody와 org.springframework.web.bind.annotation.RequestBody 혼동 주의:
@Operation 안에 사용되는 @RequestBody는 io.swagger.v3.oas.annotations.parameters.RequestBody를 임포트해야 합니다.@RequestBody는 org.springframework.web.bind.annotation.RequestBody 입니다. 둘을 헷갈리지 않도록 주의해주세요.@ExampleObject 사용: @Content 내부의 examples 배열에 @ExampleObject를 사용하여 원하는 예시 JSON 문자열을 value 필드에 넣어줄 수 있습니다. name, summary, description으로 예시에 대한 설명을 추가할 수도 있어요.schema = @Schema(implementation = UserDto.class): 여기서는 여전히 UserDto 스키마를 사용한다고 명시하지만, examples를 통해 해당 스키마에 대한 실제 데이터를 다르게 보여줄 수 있습니다.이렇게 설정하면 Swagger UI에서 각 POST /join과 DELETE /delete API를 클릭했을 때, 요청 본문(Request Body) 섹션에서 미리 정의해 둔 @ExampleObject들이 드롭다운 형태로 나타나 다른 예시 값을 선택해 볼 수 있게 됩니다.