[Swagger API] 스프링부트-그래들 스웨거 적용 방법 (3) 어노테이션으로 API 문서 정리하기

 

📄 시스템 환경

항목	내용
문서화 도구	Swagger (OpenAPI 3)
라이브러리	org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0
문서 UI 경로	http://localhost:8080/swagger-ui/index.html
인증 방식	JWT Bearer Token (Authorization: Bearer <token>)
문서 기본 설정 위치	SwaggerConfig.java (@Configuration 기반 Bean 등록)
보안 스키마	SecurityScheme.Type.HTTP - bearer, 형식: JWT

---

 

 

1. Controller 관련 어노테이션

어노테이션	설명	적용 위치
@Tag	API 그룹 지정 및 설명	클래스 (Controller 상단)
@Operation	개별 API 설명 및 요약 제공	메서드
@ApiResponse	응답 코드별 설명, 스키마 설정	메서드
@ApiResponses	여러 @ApiResponse를 묶어서 사용	메서드
@Parameter	개별 파라미터에 대한 설명	메서드 파라미터
@Hidden	Swagger 문서에서 제외	클래스, 메서드, 파라미터 등

---

@RestController
@RequestMapping("/api/users")
@Tag(name = "User API", description = "사용자 관련 API") // API 그룹 지정 및 설명
public class UserController {

    @GetMapping("/{id}")
    @Operation(
        summary = "사용자 조회", // API 요약 설명
        description = "사용자 ID를 통해 특정 사용자 정보를 조회합니다." // 상세 설명
    )
    @ApiResponse(
        responseCode = "200",
        description = "성공적으로 사용자 정보를 반환했습니다.",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = UserResponse.class) // 응답 DTO 스키마 지정
        )
    )
    public UserResponse getUserById(
        @Parameter(
            description = "조회할 사용자 ID", // 파라미터 설명
            example = "1" // 파라미터 예시
        )
        @PathVariable Long id
    ) {
        return new UserResponse(id, "user@example.com");
    }

    @Hidden // 이 메서드는 Swagger 문서에서 숨겨짐
    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        // 삭제 로직
    }
}

---

 

 

2. DTO 관련 어노테이션

어노테이션	설명	적용 위치
@Schema	DTO 필드에 대한 설명 및 예시	DTO 클래스 및 필드
@ArraySchema	배열 형태의 데이터 스키마 설정	배열 타입 DTO 필드
@Hidden	특정 DTO 필드를 문서에서 숨김	DTO 필드

 

@Schema(description = "사용자 등록 요청 DTO")
public class UserRequest {

    @Schema(description = "사용자의 이름", example = "홍길동")
    private String name;

    @Schema(description = "사용자의 이메일 주소", example = "hong@example.com")
    private String email;

    @Schema(description = "사용자의 나이", example = "25")
    private int age;
    
    @ArraySchema(schema = @Schema(description = "사용자 권한 목록", example = "ROLE_USER"))
    private List<String> roles;

    @Schema(hidden = true) // 문서에서는 보이지 않게 숨김
    private String internalMemo;

}

 

---

 

3. 보안/요청/응답 설정 관련 어노테이션

어노테이션	설명	적용 위치
@SecurityRequirement	인증이 필요한 API임을 명시 (JWT 등)	클래스 또는 메서드
@RequestBody	요청 바디에 들어오는 객체 설명	메서드 파라미터
@Content	응답 또는 요청에 포함되는 데이터의 타입 및 예시	@ApiResponse 내
@MediaType	컨텐츠 타입 지정 (application/json, 등)	내부 속성으로 사용됨

---

@RestController
@RequestMapping("/users")
@SecurityRequirement(name = "JWT") // 이 컨트롤러의 모든 메서드가 JWT 인증을 요구함
public class UserController {

    @Operation(
        summary = "사용자 등록",
        description = "새로운 사용자를 등록합니다.",
        security = { @SecurityRequirement(name = "JWT") }, // 메서드 개별 적용도 가능
        requestBody = @RequestBody(
            required = true,
            description = "등록할 사용자 정보",
            content = @Content(
                mediaType = MediaType.APPLICATION_JSON_VALUE, // 요청이 JSON 타입임을 명시
                schema = @Schema(implementation = UserRequest.class),
                examples = @ExampleObject(
                    name = "사용자 예시",
                    value = "{ \"name\": \"홍길동\", \"email\": \"hong@example.com\", \"age\": 25 }"
                )
            )
        ),
        responses = {
            @ApiResponse(
                responseCode = "200",
                description = "등록 성공",
                content = @Content(
                    mediaType = MediaType.APPLICATION_JSON_VALUE, // 응답도 JSON
                    schema = @Schema(implementation = UserResponse.class),
                    examples = @ExampleObject(
                        name = "응답 예시",
                        value = "{ \"id\": 1, \"name\": \"홍길동\", \"email\": \"hong@example.com\" }"
                    )
                )
            ),
            @ApiResponse(responseCode = "400", description = "잘못된 요청")
        }
    )
    @PostMapping
    public UserResponse createUser(@org.springframework.web.bind.annotation.RequestBody UserRequest request) {
        // 등록 로직
        return new UserResponse(1L, request.getName(), request.getEmail());
    }
}

---