Spring에서의 OpenAPI 어노테이션은 주로 Springdoc OpenAPI 라이브러리를 사용하여 API 문서를 자동으로 생성할 때 사용되며, API 문서화할 때 큰 역할을 합니다. 이번 포스트에서는 OpenAPI의 주요 어노테이션에 대해 살펴보겠습니다.

@Operation

@Operation은 특정 엔드포인트에 대한 정보를 정의합니다.

  • 속성

    속성 설명
    summary 엔드포인트에 대한 요약 설명
    description 엔드포인트에 대한 자세한 설명
    tags 태그를 사용하여 엔드포인트를 그룹화
    responses 가능한 응답을 정의
    parameters 엔드포인트의 파라미터를 정의
    requestBody 요청 본문을 정의
    deprecated 엔드포인트가 더 이상 사용되지 않음을 표시

  • 예제 코드

    @Operation(summary = "Get user by ID", description = "Returns a user when a valid ID is provided")
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // Implementation here
}


@Parameter

@Parameter는 API 메서드의 파라미터를 설명합니다.

  • 속성

    속성 설명
    name 파라미터 이름
    description 파라미터에 대한 설명
    required 파라미터의 필수 여부
    example 파라미터의 예제 값
    schema 파라미터의 스키마를 정의

  • 예제 코드

    @GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(
    @Parameter(description = "ID of the user to be obtained", required = true)
    @PathVariable Long id) {
    // Implementation here
}


@RequestBody

@RequestBody는 요청 본문을 설명합니다.

  • 속성

    속성 설명
    description 요청 본문에 대한 설명
    required 요청 본문의 필수 여부
    content 요청 본문의 내용을 정의 (미디어 타입과 스키마)

  • 예제 코드

    @Operation(summary = "Create a new user")
@PostMapping("/users")
public ResponseEntity<User> createUser(
    @RequestBody(description = "User to be created", required = true,
                content = @Content(schema = @Schema(implementation = User.class)))
    @Valid @RequestBody User user) {
    // Implementation here
}


@ApiResponses

@ApiResponses는 여러 @ApiResponse 어노테이션을 그룹화합니다.

  • 속성

    속성 설명
    value `@ApiResponse` 어노테이션 배열

  • 예제 코드

    @ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Successful operation",
        content = @Content(mediaType = "application/json",
                          schema = @Schema(implementation = User.class))),
    @ApiResponse(responseCode = "404", description = "User not found")
})
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // Implementation here
}


@ApiResponse

@ApiResponse는 가능한 응답을 설명합니다.

  • 속성

    속성 설명
    responseCode 응답 코드 (예: 200, 404)
    description 응답에 대한 설명
    content 응답 본문의 내용을 정의 (미디어 타입과 스키마)

  • 예제 코드

    @ApiResponse(responseCode = "200", description = "Successful operation",
    content = @Content(mediaType = "application/json",
                      schema = @Schema(implementation = User.class)))
@ApiResponse(responseCode = "404", description = "User not found")


@Schema

@Schema는 모델 클래스 또는 필드의 스키마를 정의합니다.

  • 속성

    속성 설명
    description 필드 또는 클래스에 대한 설명
    example 필드 또는 클래스의 예제 값
    required 필드의 필수 여부 (클래스 레벨에서 사용)

  • 예제 코드

    @Schema(description = "User entity")
public class User {
    @Schema(description = "Unique identifier of the user", example = "1", required = true)
    private Long id;

    @Schema(description = "Name of the user", example = "John Doe", required = true)
    private String name;
      
    // Other fields, getters, and setters
}


@Content

@Content는 요청 또는 응답 본문의 내용을 정의합니다.

  • 속성

    속성 설명
    mediaType 미디어 타입 (예: "application/json")
    schema 스키마를 정의
    examples 예제 값을 정의

  • 예제 코드

    @ApiResponse(responseCode = "200", description = "Successful operation",
    content = @Content(mediaType = "application/json",
                      schema = @Schema(implementation = User.class)))


@ExampleObject

@ExampleObject는 예제 객체를 정의합니다.

  • 속성

    속성 설명
    name 예제 이름
    summary 예제 요약
    description 예제에 대한 설명
    value 예제 값

  • 예제 코드

    @Schema(description = "User entity")
public class User {
    @Schema(description = "Unique identifier of the user", example = "1", required = true)
    private Long id;

    @Schema(description = "Name of the user", example = "John Doe", required = true)
    private String name;

    @Schema(description = "User email", example = "john.doe@example.com")
    private String email;
      
    // Other fields, getters, and setters
}


@ArraySchema

@ArraySchema는 배열 타입의 스키마를 정의합니다.

  • 속성

    속성 설명
    schema 배열의 요소 스키마를 정의
    maxItems 배열의 최대 아이템 수
    minItems 배열의 최소 아이템 수
    uniqueItems 배열의 아이템 고유 여부

  • 예제 코드

    @ArraySchema(schema = @Schema(implementation = User.class))
private List<User> users;