[Spring] OpenAPI 어노테이션

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;
  

---

읽어주셔서 감사합니다. 😊

Reference
ChatGPT - OpenAI