Spring, Controller 어노테이션 정리

Controller에서 자주 사용하는 어노테이션

@Tag(name = "리포트")
@RequiredArgsConstructor
@RequestMapping("/admin")
@RestController
public class CreditMonthlyReportController {
}

 

 @Tag(name = "리포트") 

• 이 어노테이션은 Swagger API 문서화에서 사용되는 태그를 지정하는 데 사용된다.
• "리포트"라는 이름으로 API를 그룹화하여, Swagger UI에서 API 문서를 더 깔끔하게 정리할 수 있다.

 

 @RequiredArgsConstructor 

• Lombok 라이브러리의 어노테이션으로, final이나 @NonNull이 붙은 필드를 자동으로 생성자에 주입하는 기능을 제공한다.
• 이 어노테이션이 있으면, @Autowired 없이도 의존성 주입이 자동으로 이루어집니다.

▹ 각각 주입하는 경우(수동으로 생성자 주입)

• 필요한 의존성에 대해서만 생성자를 주입할 수 있다.
• 이 방식은 더 명시적이고, 필요한 의존성만 주입되기 때문에 의존성 주입을 제어 할 수 있는 장점이 있다.

 

 @RequestMapping("/admin") 

• @RequestMapping은 해당 컨트롤러가 처리하는 HTTP 요청의 기본 URL 경로를 지정한다.
• "/admin"은 이 컨트롤러의 모든 API 경로가 /admin 경로 아래에 위치함을 의미한다.

 

 @RestController 

• 이 어노테이션은 @Controller와 @ResponseBody의 조합으로, 해당 클래스가 RESTful API를 처리하는 컨트롤러임을 나타낸다.
• 각 메서드는 반환값이 HTTP 응답 본문에 자동으로 직렬화된다.

---

@GetMapping("/report-credit-monthly")
@Operation(
  security = @SecurityRequirement(name = AuthConstant.SWAGGER_HEADER_AUTH),
  summary = "월별 계정 크레딧 잔액 목록 조회", description = "월별 계정 크레딧 잔액 목록 조회"
)
@ApiResponses(value = {
  @ApiResponse(responseCode = "404", description = "데이터 없음", content = @Content(schema = @Schema(hidden = true))),
})
@ResponseStatus(value = HttpStatus.OK)

 

 @GetMapping("/report") 

 

▹ HTTP GET 요청을 처리하는 메서드에 적용되는 어노테이션

URL 경로 /report에 대한 GET 요청을 이 메서드에서 처리하게 된다

• 클라이언트가 /report 엔드포인트로 GET 요청을 보내면 이 메서드가 호출된다.

 

 @Operation (Swagger/OpenAPI용) 

 

▹ Swagger(OpenAPI) 문서화에서 API에 대한 설명을 추가하는 데 사용

API에 대한 메타데이터를 정의하여, API 문서화가 더 명확하고 사용자 친화적이도록 한다.

 

security = @SecurityRequirement(name = AuthConstant.SWAGGER_HEADER_AUTH)

• Swagger UI에서 API가 인증을 요구한다는 것을 나타낸다. AuthConstant.SWAGGER_HEADER_AUTH는 인증 헤더 이름을 나타내며, 이를 통해 API 호출 시 적절한 인증이 필요함을 나타낸다.

summary = "" : 이 API의 간단한 설명을 추가

description = "" : API에 대한 추가적인 설명을 제공

 

 @ApiResponses 및 @ApiResponse (Swagger/OpenAPI용) 

 

▹ API의 응답에 대한 메타데이터를 정의

 

responseCode = "404": 응답 코드가 404일 때의 설명을 추가

description = "데이터 없음": 404 상태 코드에 대한 설명

• 이 API에서는 데이터가 없을 때 404 응답을 반환할 수 있음을 나타낸다.

content = @Content(schema = @Schema(hidden = true))

• 404 응답에서 반환되는 내용에 대한 스키마를 숨긴다. 즉, 404 응답에 대한 본문 내용은 Swagger 문서화에서 보이지 않게 된다.

 

 @ResponseStatus(value = HttpStatus.OK) 

 

▹ 해당 API가 성공적으로 처리되었을 때, HTTP 상태 코드로 200 OK를 반환하도록 지정합니다. 기본적으로 @GetMapping은 200 상태 코드를 반환하지만, 명시적으로 상태 코드를 설정하고 싶을 때 사용합니다.

• HttpStatus.OK는 클라이언트에게 요청이 성공적으로 처리되었음을 알리기 위해 200 OK 응답을 보냅니다.

Option

옵션	응답 코드	설명	예시
HttpStatus.OK	200	요청이 성공적으로 처리되었음을 나타냅니다.	데이터를 정상적으로 반환하거나 성공적인 작업 완료 시.
HttpStatus.CREATED	201	리소스가 성공적으로 생성되었음을 나타냅니다.	새로운 엔티티를 생성한 후.
HttpStatus.BAD_REQUEST	400	클라이언트의 요청이 잘못되었음을 나타냅니다. 유효하지 않은 입력, 필수 파라미터 누락 등.	유효하지 않은 데이터를 받은 경우.
HttpStatus.UNAUTHORIZED	401	인증이 필요하거나 인증 정보가 잘못된 경우.	로그인하지 않은 사용자가 보호된 리소스를 요청할 때.
HttpStatus.FORBIDDEN	403	인증은 되었지만, 해당 리소스에 접근할 권한이 없는 경우.	사용자가 권한이 없는 리소스를 요청할 때.
HttpStatus.NOT_FOUND	404	요청한 리소스를 찾을 수 없는 경우.	존재하지 않는 리소스를 요청했을 때.
HttpStatus.INTERNAL_SERVER_ERROR	500	서버 내부에서 예기치 않은 오류가 발생했을 때.	서버에서 처리할 수 없는 오류가 발생한 경우.
HttpStatus.BAD_GATEWAY	502	게이트웨이 또는 프록시 서버가 잘못된 응답을 받았을 때.	외부 서비스와 통신하는 API에서 문제가 발생했을 때.
HttpStatus.SERVICE_UNAVAILABLE	503	서버가 일시적으로 과부하되었거나 유지보수 중일 때.	서버가 다운되었거나 응답할 수 없을 때.
HttpStatus.GATEWAY_TIMEOUT	504	게이트웨이 또는 프록시 서버에서 시간 초과가 발생한 경우.	외부 API 호출이 시간 초과된 경우.