* 주의
@RestController 로 생성된 Controller에만 적용

Swagger(Springdoc OpenAPI) 어노테이션은 API 문서를 상세하고 명확하게 작성할 수 있도록 다양한 기능을 제공합니다. 주요 어노테이션을 정리하면 다음과 같습니다.

1. 클래스 수준 어노테이션

@OpenAPIDefinition

• OpenAPI 문서의 전역 설정(제목, 설명, 버전 등)을 정의합니다.

java

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;

@OpenAPIDefinition(
    info = @Info(
        title = "Demo API",
        version = "1.0",
        description = "Demo Application API Documentation"
    )
)
public class OpenApiConfig {}
 

2. 메소드 수준 어노테이션

@Operation

• API 엔드포인트의 설명, 태그 등을 정의합니다.

속성

• summary: API의 간략한 설명.
• description: API의 상세 설명.
• tags: API 태그(그룹화).
• responses: 가능한 응답 코드와 설명.

java

import io.swagger.v3.oas.annotations.Operation;

@Operation(
    summary = "인사 메시지 반환",
    description = "사용자의 이름을 기반으로 인사 메시지를 반환합니다."
)
@GetMapping("/hello")
public String sayHello() {
    return "Hello, World!";
}
 

3. 응답 관련 어노테이션

@ApiResponse

• 특정 응답 코드와 설명을 정의합니다.

@ApiResponses

• 여러 @ApiResponse를 그룹화하여 사용합니다.

java

import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@ApiResponses({
    @ApiResponse(responseCode = "200", description = "성공적으로 메시지 반환"),
    @ApiResponse(responseCode = "404", description = "리소스를 찾을 수 없음")
})
@GetMapping("/hello")
public String sayHello() {
    return "Hello, World!";
}
 

4. 요청 파라미터 관련 어노테이션

@Parameter

• 요청 파라미터를 문서화합니다.

속성

• description: 파라미터 설명.
• required: 필수 여부 지정.
• example: 예제 값.

java

import io.swagger.v3.oas.annotations.Parameter;

@GetMapping("/hello")
public String sayHello(
    @Parameter(description = "사용자의 이름", required = false, example = "John")
    @RequestParam(required = false) String name
) {
    return name != null ? "Hello, " + name + "!" : "Hello, World!";
}
 

5. 모델 관련 어노테이션

@Schema

• 객체 모델의 필드 또는 클래스에 대한 설명을 추가합니다.

속성

• description: 필드나 클래스에 대한 설명.
• example: 예제 값 제공.

java

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

public class User {

    @Schema(description = "사용자 ID", example = "123")
    private Long id;

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

    // Getters and Setters
}
 

@ArraySchema

• 배열 타입의 모델을 문서화합니다.

java

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

@ArraySchema(
    schema = @Schema(description = "사용자 목록"),
    minItems = 1,
    uniqueItems = true
)
private List<User> users;
 

6. 파일 업로드 관련 어노테이션

@Content와 @MediaType

• 파일 업로드 및 다양한 데이터 형식을 처리하는 API를 문서화합니다.

java

import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.parameters.RequestBody;

@RequestBody(
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = User.class)
    )
)
@PostMapping("/upload")
public String uploadFile() {
    return "File uploaded!";
}
 

7. 추가 유용한 어노테이션

@Hidden

• 특정 엔드포인트나 파라미터를 Swagger 문서에서 숨깁니다.

java

import io.swagger.v3.oas.annotations.Hidden;

@Hidden
@GetMapping("/hidden")
public String hiddenEndpoint() {
    return "This will not appear in Swagger UI.";
}
 

@Tag

• API 태그를 명시적으로 정의합니다.

java

import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "User API", description = "사용자 관련 API")
@RestController
public class UserController {}
 

정리

Springdoc OpenAPI의 주요 어노테이션은 크게 클래스 수준, 메소드 수준, 요청 및 응답 수준, 모델 수준으로 나눌 수 있습니다. 이를 적절히 활용하면 API 문서를 더 명확하고 읽기 쉽게 작성할 수 있습니다.