[TIL, 일일 회고] 2024.10.23 - Spring boot Swagger 주요 어노테이션

Swagger 주요 어노테이션

OpenAPI 3.x에 대응하는 주요 Swagger 어노테이션은 다음과 같습니다.

@Operation

@Operation(summary = "허브 목록 조회", description = "모든 허브의 정보를 조회합니다.")

• API 엔드포인트에 대한 정보를 제공하는 어노테이션입니다.
• summary, description, tags, responses 등을 설정할 수 있습니다.

@Parameter

@Parameter(name = "hubId", description = "조회할 허브의 ID", example = "123e4567-e89b-12d3-a456-426614174000")

 

• 엔드포인트의 매개변수에 대한 설명을 추가하는 어노테이션입니다.
• name, description, example 등을 설정하여 파라미터의 정보를 자세히 명시할 수 있습니다.

@ApiResponse

@ApiResponse(responseCode = "400", description = "잘못된 요청입니다")

 

• 특정 HTTP 응답에 대한 설명을 제공하는 어노테이션입니다.
• responseCode, description, content 등을 설정할 수 있습니다.

@ApiResponses

@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "성공적으로 조회됨"),
    @ApiResponse(responseCode = "404", description = "허브를 찾을 수 없음")
})

 

• API의 응답 상태 코드와 설명을 명시하는 데 사용됩니다.
• 여러 @ApiResponse 어노테이션을 포함하여 다양한 응답 상황을 기술할 수 있습니다.

 

 

@Schema

@Schema(description = "허브 이름", example = "서울 물류 센터")
private String name;

 

• 엔티티나 DTO 클래스의 속성에 대한 설명을 추가하는 어노테이션입니다.
• description, example, defaultValue, required 등을 설정하여 스키마 정보를 세부적으로 제공할 수 있습니다.

@RequestBody

@RequestBody(description = "허브 정보", required = true)

 

 

• 요청 본문에 대해 설명하는 어노테이션입니다.
• 주로 POST나 PUT 요청에서 사용되며, description, required 등을 설정할 수 있습니다.

 

@Api

@Api(tags = "허브 API", description = "허브 정보를 관리하는 API")

• 클래스 레벨에서 사용하여, 컨트롤러에 대한 전반적인 설명과 태그를 설정할 수 있습니다.