[Java / annotation] - @Schema

개요

 

  @Schema 어노테이션은 Springdoc OpenAPI와 같은 도구에서 사용하는 어노테이션으로, Swagger UI 또는 OpenAPI 문서에서 데이터 모델(클래스, 필드 등)의 메타데이터를 설명하는 데 사용된다. 주로 애플리케이션의 API 스펙을 정의하고 문서화할 때 사용된다.

 

이 어노테이션은 클래스나 필드에 대한 설명, 예시 값, 기본 값 등을 지정할 수 있게 해주며, API 문서화를 더욱 명확하게 만들 수 있다는 장점을 가지고 있다.

 

사용 예시 :

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "사용자 정보를 담고 있는 클래스")
public class User {
	
    @Schema(description = "사용자의 고유 ID", example = "12345", required = true)
    private Long id;

    @Schema(description = "사용자의 이름", example = "John Doe")
    private String name;

    @Schema(description = "사용자의 나이", example = "30")
    private int age;

	// 생성자, 게터, 세터 생략

}

 

주요 속성들은 아래와 같다

- description : 해당 클래스나 필드에 대한 설명을 제공한다. 이를 통해 API 문서를 보는 사람들이 해당 필드의 역할을 이해하기 쉽게 된다.
ex) description = “사용자의 고유 ID”

- example : 필드에 대한 예시 값을 지정할 수 있다. 이를 통해 문서를 보는 사람들이 어떤 형식의 값이 들어가는지 쉽게 이해할 수 있다.
ex) example = “12345”

- required : 해당 필드가 필수인지 여부를 설정한다. 기본값은 false 이며, true로 설정하면 문서화된 API에서 필수 필드로 표시된다.
ex) required = true

- defaultValue : 필드의 기본값을 지정할 수 있다.
ex) defaultValue = “guest”

컨트롤러와 연계된 API 문서화

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "사용자 정보 조회", description = "특정 ID에 해당하는 사용자의 정보를 반환합니다.")
    public ResponseEntity<User> getUserById(
            @PathVariable @Parameter(description = "조회할 사용자의 ID", example = "12345") Long id) {
        User user = new User();
        // User 정보를 설정하는 코드 생략
        return ResponseEntity.ok(user);
    }
}

 

 위 코드에서, @Operation과 @Parameter를 사용해 컨트롤러의 메서드와 매개변수를 문서화 할 수 있으며, User 클래스의 필드는 @Schema를 통해 정의된 설명이 API 문서에 그대로 반영된다.

 

이를 통해, API 사용자나 다른 개발자들이 API의 필드와 역할을 더 잘 이해할 수 있도록 도와준다는 사실을 알 수 있다.