Spring Boot에서 Swagger(OpenAPI) 어노테이션 정리하기

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

@OpenAPIDefinition(
    info = @Info(
        title = "사용자 관리 API",
        description = "사용자 정보 조회, 등록, 수정, 삭제 기능 제공",
        version = "v1.0"
    )
)
@Configuration
public class OpenApiConfig {
    //
}

import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @Operation(summary = "단일 사용자 조회", description = "ID를 통해 특정 사용자의 정보를 조회합니다.")
    @GetMapping("/{id}")
    public User getUserById(
        @Parameter(name = "id", description = "사용자 ID", in = ParameterIn.PATH, required = true)
        @PathVariable Long id) {
        // ...
        return new User();
    }
}

import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.http.MediaType;

@Operation(summary = "새 사용자 등록", description = "새로운 사용자를 등록합니다.")
@ApiResponses(value = {
    @ApiResponse(responseCode = "201", description = "사용자 등록 성공", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = User.class))),
    @ApiResponse(responseCode = "400", description = "잘못된 요청", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE))
})
@PostMapping
public User createUser(@RequestBody User user) {
    // ...
    return user;
}

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

@Schema(description = "사용자 정보 DTO")
public class User {
    
    @Schema(description = "사용자 ID", example = "1")
    private Long id;

    @Schema(description = "사용자 이름", example = "홍길동", required = true)
    private String name;

    @Schema(description = "사용자 이메일", example = "test@example.com")
    private String email;

    // Getter, Setter
}