Spring 16: API 문서화

기본 사용법

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

    @Operation(
        summary = "사용자 정보 조회",
        description = "사용자 ID를 통해 특정 사용자의 상세 정보를 조회합니다. " +
                     "존재하지 않는 사용자 ID인 경우 404 오류를 반환합니다.",
        operationId = "getUserById",
        tags = {"User Management"}
    )
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200", 
            description = "사용자 조회 성공",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = UserResponse.class)
            )
        ),
        @ApiResponse(
            responseCode = "404", 
            description = "사용자를 찾을 수 없음"
        )
    })
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(
        @Parameter(
            description = "조회할 사용자의 고유 ID", 
            required = true,
            example = "1"
        ) 
        @PathVariable Long id
    ) {
        UserResponse user = userService.findById(id);
        return ResponseEntity.ok(user);
    }
}

다양한 매개변수 타입 문서화

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @Operation(summary = "상품 목록 조회")
    @GetMapping
    public ResponseEntity<PagedResponse<Product>> getProducts(
        @Parameter(
            description = "페이지 번호 (1부터 시작)", 
            example = "1",
            schema = @Schema(type = "integer", minimum = "1")
        )
        @RequestParam(defaultValue = "1") int page,
        
        @Parameter(
            description = "페이지 크기 (최대 100)", 
            example = "20",
            schema = @Schema(type = "integer", maximum = "100")
        )
        @RequestParam(defaultValue = "20") int size,
        
        @Parameter(
            description = "상품명 검색 키워드", 
            example = "스마트폰",
            required = false
        )
        @RequestParam(required = false) String keyword,
        
        @Parameter(
            description = "클라이언트 언어 설정", 
            example = "ko-KR",
            in = ParameterIn.HEADER
        )
        @RequestHeader(value = "Accept-Language") String language
    ) {
        return ResponseEntity.ok(
            productService.getProducts(page, size, keyword, language)
        );
    }
}

포괄적인 응답 문서화

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @Operation(summary = "주문 생성")
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "201",
            description = "주문 생성 성공",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = OrderResponse.class),
                examples = @ExampleObject(
                    name = "성공 예제",
                    value = """
                    {
                        "orderId": "ORD-2024-001",
                        "status": "PENDING",
                        "totalAmount": 150000,
                        "createdAt": "2024-01-15T10:30:00Z"
                    }
                    """
                )
            )
        ),
        @ApiResponse(
            responseCode = "400",
            description = "잘못된 요청 데이터",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = ErrorResponse.class)
            )
        ),
        @ApiResponse(
            responseCode = "422",
            description = "비즈니스 로직 오류",
            content = @Content(
                mediaType = "application/json",
                examples = @ExampleObject(
                    name = "재고 부족",
                    value = """
                    {
                        "error": "INSUFFICIENT_STOCK",
                        "message": "상품 재고가 부족합니다.",
                        "productId": 1,
                        "availableQuantity": 2
                    }
                    """
                )
            )
        )
    })
    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(
        @RequestBody @Valid OrderCreateRequest request
    ) {
        OrderResponse order = orderService.createOrder(request);
        return ResponseEntity.status(201).body(order);
    }
}

DTO 클래스 문서화

@Schema(
    name = "UserCreateRequest",
    description = "사용자 생성 요청 데이터"
)
public class UserCreateRequest {

    @Schema(
        description = "사용자 이름",
        example = "홍길동",
        requiredMode = Schema.RequiredMode.REQUIRED,
        minLength = 2,
        maxLength = 50
    )
    @NotBlank(message = "이름은 필수입니다.")
    @Size(min = 2, max = 50)
    private String name;

    @Schema(
        description = "이메일 주소",
        example = "hong@example.com",
        requiredMode = Schema.RequiredMode.REQUIRED,
        format = "email"
    )
    @NotBlank(message = "이메일은 필수입니다.")
    @Email(message = "올바른 이메일 형식이 아닙니다.")
    private String email;

    @Schema(
        description = "나이",
        example = "30",
        minimum = "18",
        maximum = "120"
    )
    @Min(value = 18, message = "나이는 18세 이상이어야 합니다.")
    @Max(value = 120, message = "나이는 120세 이하여야 합니다.")
    private Integer age;

    @Schema(
        description = "전화번호",
        example = "010-1234-5678",
        pattern = "^010-\\d{4}-\\d{4}$"
    )
    @Pattern(regexp = "^010-\\d{4}-\\d{4}$")
    private String phoneNumber;

    // getters and setters...
}

@Schema(description = "사용자 응답 데이터")
public class UserResponse {

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

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

    @Schema(description = "이메일 주소", example = "hong@example.com")
    private String email;

    @Schema(description = "계정 생성일", example = "2024-01-15T10:30:00Z")
    private LocalDateTime createdAt;

    @Schema(description = "계정 상태", example = "ACTIVE")
    private UserStatus status;

    // getters and setters...
}

기본 DTO 문서화

@Schema(
    name = "ProductCreateRequest",
    description = "상품 생성 요청 데이터"
)
public class ProductCreateRequest {

    @Schema(
        description = "상품명",
        example = "iPhone 15 Pro",
        requiredMode = Schema.RequiredMode.REQUIRED,
        minLength = 1,
        maxLength = 100
    )
    @NotBlank(message = "상품명은 필수입니다.")
    @Size(min = 1, max = 100)
    private String name;

    @Schema(
        description = "상품 가격 (원)",
        example = "1200000",
        requiredMode = Schema.RequiredMode.REQUIRED,
        minimum = "0"
    )
    @NotNull(message = "가격은 필수입니다.")
    @DecimalMin(value = "0")
    private BigDecimal price;

    @Schema(
        description = "카테고리 ID",
        example = "1",
        requiredMode = Schema.RequiredMode.REQUIRED
    )
    @NotNull(message = "카테고리는 필수입니다.")
    @Positive
    private Long categoryId;

    // getters and setters...
}

다양한 예제 시나리오

@Schema(description = "주문 생성 요청")
public class OrderCreateRequest {

    @Schema(
        description = "주문 항목 목록",
        requiredMode = Schema.RequiredMode.REQUIRED
    )
    @NotEmpty(message = "주문 항목은 최소 1개 이상이어야 합니다.")
    @Valid
    private List<OrderItem> items;

    @Schema(
        description = "배송 주소",
        requiredMode = Schema.RequiredMode.REQUIRED
    )
    @NotNull(message = "배송 주소는 필수입니다.")
    @Valid
    private DeliveryAddress deliveryAddress;

    @Schema(
        description = "할인 쿠폰 코드",
        example = "WELCOME20"
    )
    private String couponCode;

    // getters and setters...
}

// Controller에서 예제 사용
@Operation(summary = "주문 생성")
@ApiResponse(
    responseCode = "201",
    description = "주문 생성 성공",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = OrderResponse.class),
        examples = {
            @ExampleObject(
                name = "일반 주문",
                description = "할인 없는 일반 주문",
                value = """
                {
                    "orderId": "ORD-2024-001",
                    "status": "PENDING",
                    "totalAmount": 150000,
                    "items": [
                        {
                            "productId": 1,
                            "productName": "iPhone 15",
                            "quantity": 1,
                            "unitPrice": 150000,
                            "totalPrice": 150000
                        }
                    ],
                    "deliveryAddress": {
                        "recipient": "홍길동",
                        "phone": "010-1234-5678",
                        "address": "서울시 강남구 테헤란로 123",
                        "zipCode": "06234"
                    },
                    "createdAt": "2024-01-15T10:30:00Z"
                }
                """
            ),
            @ExampleObject(
                name = "할인 적용 주문",
                description = "쿠폰 할인이 적용된 주문",
                value = """
                {
                    "orderId": "ORD-2024-002",
                    "status": "PENDING",
                    "originalAmount": 200000,
                    "discountAmount": 40000,
                    "totalAmount": 160000,
                    "couponCode": "WELCOME20",
                    "items": [
                        {
                            "productId": 1,
                            "productName": "iPhone 15",
                            "quantity": 1,
                            "unitPrice": 150000,
                            "totalPrice": 150000
                        },
                        {
                            "productId": 2,
                            "productName": "AirPods Pro",
                            "quantity": 1,
                            "unitPrice": 50000,
                            "totalPrice": 50000
                        }
                    ],
                    "createdAt": "2024-01-15T10:30:00Z"
                }
                """
            )
        }
    )
)

유효성 검증 통합 문서화

@Schema(description = "사용자 등록 요청")
public class UserRegistrationRequest {

    @Schema(
        description = "사용자 이름 (한글, 영문만 허용)",
        example = "홍길동",
        requiredMode = Schema.RequiredMode.REQUIRED,
        minLength = 2,
        maxLength = 50,
        pattern = "^[가-힣a-zA-Z\\s]+$"
    )
    @NotBlank(message = "이름은 필수입니다.")
    @Size(min = 2, max = 50, message = "이름은 2-50자 사이여야 합니다.")
    @Pattern(
        regexp = "^[가-힣a-zA-Z\\s]+$", 
        message = "이름은 한글, 영문, 공백만 허용됩니다."
    )
    private String name;

    @Schema(
        description = "이메일 주소",
        example = "user@example.com",
        requiredMode = Schema.RequiredMode.REQUIRED,
        format = "email",
        maxLength = 100
    )
    @NotBlank(message = "이메일은 필수입니다.")
    @Email(message = "올바른 이메일 형식이 아닙니다.")
    @Size(max = 100, message = "이메일은 100자를 초과할 수 없습니다.")
    private String email;

    @Schema(
        description = "비밀번호 (8-20자, 영문+숫자+특수문자 조합)",
        example = "Password123!",
        requiredMode = Schema.RequiredMode.REQUIRED,
        minLength = 8,
        maxLength = 20,
        pattern = "^(?=.*[a-zA-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]+$"
    )
    @NotBlank(message = "비밀번호는 필수입니다.")
    @Size(min = 8, max = 20, message = "비밀번호는 8-20자 사이여야 합니다.")
    @Pattern(
        regexp = "^(?=.*[a-zA-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]+$",
        message = "비밀번호는 영문, 숫자, 특수문자를 포함해야 합니다."
    )
    private String password;

    @Schema(
        description = "나이",
        example = "25",
        minimum = "14",
        maximum = "120",
        requiredMode = Schema.RequiredMode.REQUIRED
    )
    @NotNull(message = "나이는 필수입니다.")
    @Min(value = 14, message = "나이는 14세 이상이어야 합니다.")
    @Max(value = 120, message = "나이는 120세 이하여야 합니다.")
    private Integer age;

    @Schema(
        description = "전화번호 (010-XXXX-XXXX 형식)",
        example = "010-1234-5678",
        pattern = "^010-\\d{4}-\\d{4}$"
    )
    @Pattern(
        regexp = "^010-\\d{4}-\\d{4}$",
        message = "전화번호는 010-XXXX-XXXX 형식이어야 합니다."
    )
    private String phoneNumber;

    @Schema(
        description = "개인정보 처리방침 동의",
        example = "true",
        requiredMode = Schema.RequiredMode.REQUIRED
    )
    @NotNull(message = "개인정보 처리방침 동의는 필수입니다.")
    @AssertTrue(message = "개인정보 처리방침에 동의해야 합니다.")
    private Boolean privacyAgreement;

    // getters and setters...
}

Enum 문서화 예제

@Schema(description = "주문 상태")
public enum OrderStatus {
    @Schema(description = "주문 대기")
    PENDING("주문 대기"),
    
    @Schema(description = "결제 완료")
    PAID("결제 완료"),
    
    @Schema(description = "배송 준비중")
    PREPARING("배송 준비중"),
    
    @Schema(description = "배송중")
    SHIPPING("배송중"),
    
    @Schema(description = "배송 완료")
    DELIVERED("배송 완료"),
    
    @Schema(description = "주문 취소")
    CANCELLED("주문 취소");

    private final String description;

    OrderStatus(String description) {
        this.description = description;
    }

    public String getDescription() {
        return description;
    }
}

// DTO에서 Enum 사용
@Schema(description = "주문 정보")
public class OrderResponse {

    @Schema(
        description = "주문 상태",
        example = "PENDING",
        allowableValues = {"PENDING", "PAID", "PREPARING", "SHIPPING", "DELIVERED", "CANCELLED"}
    )
    private OrderStatus status;

    @Schema(
        description = "우선순위",
        example = "HIGH",
        implementation = Priority.class
    )
    private Priority priority;

    // getters and setters...
}

JWT SecurityScheme 설정

@Configuration
public class OpenApiSecurityConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("E-Commerce API")
                        .version("1.0.0")
                        .description("JWT 인증을 사용하는 온라인 쇼핑몰 API"))
                .addSecurityItem(new SecurityRequirement()
                        .addList("Bearer Authentication"))
                .components(new Components()
                        .addSecuritySchemes("Bearer Authentication", 
                                createAPIKeyScheme()));
    }

    private SecurityScheme createAPIKeyScheme() {
        return new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .bearerFormat("JWT")
                .scheme("bearer")
                .description("JWT 토큰을 입력하세요. 'Bearer ' 접두사는 자동으로 추가됩니다.")
                .name("Authorization")
                .in(SecurityScheme.In.HEADER);
    }

    // OAuth2 설정 (선택사항)
    private SecurityScheme createOAuth2Scheme() {
        return new SecurityScheme()
                .type(SecurityScheme.Type.OAUTH2)
                .description("OAuth2 인증")
                .flows(new OAuthFlows()
                        .authorizationCode(new OAuthFlow()
                                .authorizationUrl("https://auth.example.com/oauth/authorize")
                                .tokenUrl("https://auth.example.com/oauth/token")
                                .scopes(new Scopes()
                                        .addString("read", "읽기 권한")
                                        .addString("write", "쓰기 권한")
                                        .addString("admin", "관리자 권한"))));
    }
}

권한별 API 문서화

@RestController
@RequestMapping("/api/products")
@Tag(name = "Product Management", description = "상품 관리 API")
public class ProductController {

    // 공개 API - 인증 불필요
    @Operation(
        summary = "상품 목록 조회",
        description = "모든 사용자가 접근 가능한 상품 목록 조회 API"
    )
    @GetMapping
    public ResponseEntity<PagedResponse<Product>> getProducts(
        @Parameter(description = "페이지 번호") @RequestParam(defaultValue = "1") int page,
        @Parameter(description = "페이지 크기") @RequestParam(defaultValue = "20") int size
    ) {
        return ResponseEntity.ok(productService.getProducts(page, size));
    }

    // 인증 필요 API
    @Operation(
        summary = "상품 상세 조회",
        description = "로그인한 사용자만 접근 가능한 상품 상세 정보 조회"
    )
    @SecurityRequirement(name = "Bearer Authentication")
    @GetMapping("/{id}")
    public ResponseEntity<ProductDetail> getProduct(
        @Parameter(description = "상품 ID") @PathVariable Long id
    ) {
        return ResponseEntity.ok(productService.getProductDetail(id));
    }

    // 관리자 권한 필요 API
    @Operation(
        summary = "상품 생성",
        description = "관리자 권한이 필요한 상품 생성 API"
    )
    @SecurityRequirement(name = "Bearer Authentication")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "201", description = "상품 생성 성공"),
        @ApiResponse(responseCode = "401", description = "인증 실패"),
        @ApiResponse(responseCode = "403", description = "권한 부족 - 관리자 권한 필요")
    })
    @PreAuthorize("hasRole('ADMIN')")
    @PostMapping
    public ResponseEntity<Product> createProduct(
        @RequestBody @Valid ProductCreateRequest request
    ) {
        Product product = productService.createProduct(request);
        return ResponseEntity.status(201).body(product);
    }

    // 소유자 또는 관리자 권한 필요 API
    @Operation(
        summary = "상품 수정",
        description = "상품 소유자 또는 관리자만 수정 가능"
    )
    @SecurityRequirement(name = "Bearer Authentication")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "상품 수정 성공"),
        @ApiResponse(responseCode = "401", description = "인증 실패"),
        @ApiResponse(responseCode = "403", description = "권한 부족 - 소유자 또는 관리자 권한 필요"),
        @ApiResponse(responseCode = "404", description = "상품을 찾을 수 없음")
    })
    @PreAuthorize("hasRole('ADMIN') or @productService.isOwner(#id, authentication.name)")
    @PutMapping("/{id}")
    public ResponseEntity<Product> updateProduct(
        @Parameter(description = "상품 ID") @PathVariable Long id,
        @RequestBody @Valid ProductUpdateRequest request
    ) {
        Product product = productService.updateProduct(id, request);
        return ResponseEntity.ok(product);
    }
}

인증 API 문서화

@RestController
@RequestMapping("/api/auth")
@Tag(name = "Authentication", description = "인증 관련 API")
public class AuthController {

    @Operation(
        summary = "사용자 로그인",
        description = "이메일과 비밀번호로 로그인하여 JWT 토큰을 발급받습니다."
    )
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200",
            description = "로그인 성공",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = LoginResponse.class),
                examples = @ExampleObject(
                    name = "로그인 성공",
                    value = """
                    {
                        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
                        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
                        "tokenType": "Bearer",
                        "expiresIn": 3600,
                        "user": {
                            "id": 1,
                            "email": "user@example.com",
                            "name": "홍길동",
                            "role": "USER"
                        }
                    }
                    """
                )
            )
        ),
        @ApiResponse(
            responseCode = "401",
            description = "로그인 실패",
            content = @Content(
                mediaType = "application/json",
                examples = @ExampleObject(
                    name = "로그인 실패",
                    value = """
                    {
                        "error": "INVALID_CREDENTIALS",
                        "message": "이메일 또는 비밀번호가 올바르지 않습니다.",
                        "timestamp": "2024-01-15T10:30:00Z"
                    }
                    """
                )
            )
        ),
        @ApiResponse(
            responseCode = "423",
            description = "계정 잠김",
            content = @Content(
                mediaType = "application/json",
                examples = @ExampleObject(
                    name = "계정 잠김",
                    value = """
                    {
                        "error": "ACCOUNT_LOCKED",
                        "message": "로그인 시도 횟수 초과로 계정이 잠겼습니다.",
                        "lockUntil": "2024-01-15T11:30:00Z",
                        "timestamp": "2024-01-15T10:30:00Z"
                    }
                    """
                )
            )
        )
    })
    @PostMapping("/login")
    public ResponseEntity<LoginResponse> login(
        @RequestBody @Valid LoginRequest request
    ) {
        LoginResponse response = authService.login(request);
        return ResponseEntity.ok(response);
    }

    @Operation(
        summary = "토큰 갱신",
        description = "Refresh Token을 사용하여 새로운 Access Token을 발급받습니다."
    )
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200",
            description = "토큰 갱신 성공",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = TokenRefreshResponse.class)
            )
        ),
        @ApiResponse(
            responseCode = "401",
            description = "유효하지 않은 Refresh Token",
            content = @Content(
                mediaType = "application/json",
                examples = @ExampleObject(
                    value = """
                    {
                        "error": "INVALID_REFRESH_TOKEN",
                        "message": "유효하지 않은 리프레시 토큰입니다.",
                        "timestamp": "2024-01-15T10:30:00Z"
                    }
                    """
                )
            )
        )
    })
    @PostMapping("/refresh")
    public ResponseEntity<TokenRefreshResponse> refreshToken(
        @RequestBody @Valid TokenRefreshRequest request
    ) {
        TokenRefreshResponse response = authService.refreshToken(request);
        return ResponseEntity.ok(response);
    }

    @Operation(
        summary = "로그아웃",
        description = "현재 사용자를 로그아웃하고 토큰을 무효화합니다."
    )
    @SecurityRequirement(name = "Bearer Authentication")
    @ApiResponse(responseCode = "200", description = "로그아웃 성공")
    @ApiResponse(responseCode = "401", description = "인증 실패")
    @PostMapping("/logout")
    public ResponseEntity<Void> logout(HttpServletRequest request) {
        String token = extractTokenFromRequest(request);
        authService.logout(token);
        return ResponseEntity.ok().build();
    }
}

보안 DTO 문서화

@Schema(description = "로그인 요청")
public class LoginRequest {

    @Schema(
        description = "이메일 주소",
        example = "user@example.com",
        requiredMode = Schema.RequiredMode.REQUIRED
    )
    @NotBlank(message = "이메일은 필수입니다.")
    @Email(message = "올바른 이메일 형식이 아닙니다.")
    private String email;

    @Schema(
        description = "비밀번호",
        example = "password123",
        requiredMode = Schema.RequiredMode.REQUIRED,
        format = "password"
    )
    @NotBlank(message = "비밀번호는 필수입니다.")
    private String password;

    @Schema(
        description = "로그인 상태 유지 여부",
        example = "false",
        defaultValue = "false"
    )
    private Boolean rememberMe = false;

    // getters and setters...
}

@Schema(description = "로그인 응답")
public class LoginResponse {

    @Schema(
        description = "액세스 토큰",
        example = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    )
    private String accessToken;

    @Schema(
        description = "리프레시 토큰",
        example = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    )
    private String refreshToken;

    @Schema(
        description = "토큰 타입",
        example = "Bearer",
        defaultValue = "Bearer"
    )
    private String tokenType = "Bearer";

    @Schema(
        description = "토큰 만료 시간 (초)",
        example = "3600"
    )
    private Long expiresIn;

    @Schema(description = "사용자 정보")
    private UserInfo user;

    // getters and setters...
}

@Schema(description = "사용자 정보 (민감 정보 제외)")
public class UserInfo {

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

    @Schema(description = "이메일", example = "user@example.com")
    private String email;

    @Schema(description = "이름", example = "홍길동")
    private String name;

    @Schema(description = "역할", example = "USER")
    private String role;

    @Schema(description = "프로필 이미지 URL", example = "https://example.com/profile.jpg")
    private String profileImageUrl;

    // 비밀번호, 내부 ID 등 민감한 정보는 제외

    // getters and setters...
}

GroupedOpenApi 설정

@Configuration
public class OpenApiGroupConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public")
                .displayName("Public APIs")
                .pathsToMatch("/api/public/**")
                .addOperationCustomizer((operation, handlerMethod) -> {
                    operation.addTagsItem("Public");
                    return operation;
                })
                .build();
    }

    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("user")
                .displayName("User Management")
                .pathsToMatch("/api/users/**", "/api/auth/**")
                .packagesToScan("com.example.controller.user")
                .addOperationCustomizer((operation, handlerMethod) -> {
                    // 사용자 관련 API에 공통 태그 추가
                    operation.addTagsItem("User Management");
                    return operation;
                })
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin")
                .displayName("Admin APIs")
                .pathsToMatch("/api/admin/**")
                .packagesToScan("com.example.controller.admin")
                .addOpenApiCustomizer(openApi -> {
                    // 관리자 API에 보안 요구사항 추가
                    openApi.addSecurityItem(new SecurityRequirement()
                            .addList("Bearer Authentication"));
                    return openApi;
                })
                .build();
    }

    @Bean
    public GroupedOpenApi productApi() {
        return GroupedOpenApi.builder()
                .group("product")
                .displayName("Product Management")
                .pathsToMatch("/api/products/**", "/api/categories/**")
                .addOperationCustomizer((operation, handlerMethod) -> {
                    // 상품 관련 API 커스터마이징
                    if (handlerMethod.getMethod().isAnnotationPresent(PreAuthorize.class)) {
                        operation.addTagsItem("Requires Authentication");
                    }
                    return operation;
                })
                .build();
    }

    @Bean
    public GroupedOpenApi orderApi() {
        return GroupedOpenApi.builder()
                .group("order")
                .displayName("Order & Payment")
                .pathsToMatch("/api/orders/**", "/api/payments/**")
                .packagesToScan("com.example.controller.order", "com.example.controller.payment")
                .build();
    }

    // 내부 API (개발자용)
    @Bean
    @Profile("dev")
    public GroupedOpenApi internalApi() {
        return GroupedOpenApi.builder()
                .group("internal")
                .displayName("Internal APIs (Dev Only)")
                .pathsToMatch("/api/internal/**")
                .addOperationCustomizer((operation, handlerMethod) -> {
                    operation.addTagsItem("Internal");
                    operation.setDescription(
                        "⚠️ 내부 개발용 API입니다. 운영 환경에서는 사용할 수 없습니다."
                    );
                    return operation;
                })
                .build();
    }
}

버전별 API 문서화

@Configuration
public class ApiVersionConfig {

    @Bean
    public GroupedOpenApi apiV1() {
        return GroupedOpenApi.builder()
                .group("v1")
                .displayName("API v1.0 (Deprecated)")
                .pathsToMatch("/api/v1/**")
                .addOpenApiCustomizer(openApi -> {
                    openApi.info(new Info()
                            .title("E-Commerce API v1.0")
                            .version("1.0.0")
                            .description("⚠️ **사용 중단 예정** - 2024년 12월 31일부터 지원 중단\n\n" +
                                       "새로운 개발에는 v2 API를 사용해주세요.")
                            .contact(new Contact()
                                    .name("API Support")
                                    .email("api-support@example.com"))
                            .license(new License()
                                    .name("MIT")
                                    .url("https://opensource.org/licenses/MIT")));
                    return openApi;
                })
                .addOperationCustomizer((operation, handlerMethod) -> {
                    // v1 API에 deprecated 표시
                    operation.setDeprecated(true);
                    if (operation.getDescription() != null) {
                        operation.setDescription(
                            "⚠️ **Deprecated**: " + operation.getDescription() + 
                            "\n\n새로운 v2 API를 사용해주세요."
                        );
                    }
                    return operation;
                })
                .build();
    }

    @Bean
    public GroupedOpenApi apiV2() {
        return GroupedOpenApi.builder()
                .group("v2")
                .displayName("API v2.0 (Current)")
                .pathsToMatch("/api/v2/**")
                .addOpenApiCustomizer(openApi -> {
                    openApi.info(new Info()
                            .title("E-Commerce API v2.0")
                            .version("2.0.0")
                            .description("현재 권장되는 API 버전입니다.\n\n" +
                                       "**주요 개선사항:**\n" +
                                       "- 향상된 성능\n" +
                                       "- 더 나은 오류 처리\n" +
                                       "- 확장된 기능\n" +
                                       "- GraphQL 지원")
                            .contact(new Contact()
                                    .name("API Support")
                                    .email("api-support@example.com")));
                    return openApi;
                })
                .build();
    }

    @Bean
    @Profile("dev")
    public GroupedOpenApi apiV3Beta() {
        return GroupedOpenApi.builder()
                .group("v3-beta")
                .displayName("API v3.0 (Beta)")
                .pathsToMatch("/api/v3/**")
                .addOpenApiCustomizer(openApi -> {
                    openApi.info(new Info()
                            .title("E-Commerce API v3.0 Beta")
                            .version("3.0.0-beta")
                            .description("🚧 **베타 버전** - 개발 중인 차세대 API\n\n" +
                                       "**새로운 기능:**\n" +
                                       "- 실시간 알림\n" +
                                       "- 고급 검색\n" +
                                       "- AI 추천 시스템\n\n" +
                                       "⚠️ 베타 버전이므로 운영 환경에서 사용하지 마세요."));
                    return openApi;
                })
                .addOperationCustomizer((operation, handlerMethod) -> {
                    operation.addTagsItem("Beta");
                    return operation;
                })
                .build();
    }
}

UI 테마 커스터마이징

# application.yml - 고급 Swagger UI 설정
springdoc:
  swagger-ui:
    # 기본 설정
    path: /swagger-ui.html
    enabled: true
    
    # 레이아웃 및 표시 설정
    layout: StandaloneLayout
    deep-linking: true
    display-operation-id: false
    default-models-expand-depth: 1
    default-model-expand-depth: 1
    default-model-rendering: example
    
    # 필터 및 정렬
    filter: true
    operations-sorter: method
    tags-sorter: alpha
    
    # 기능 설정
    try-it-out-enabled: true
    request-duration: true
    validator-url: none
    show-extensions: true
    show-common-extensions: true
    
    # 커스텀 리소스
    custom-css-url: /swagger-ui/custom.css
    custom-js-url: /swagger-ui/custom.js
    
    # 브랜딩
    doc-expansion: none
    persist-authorization: true
    
    # OAuth 설정
    oauth:
      client-id: swagger-ui
      client-secret: swagger-ui-secret
      realm: swagger-ui-realm
      app-name: E-Commerce API
      scope-separator: " "
      use-pkce-with-authorization-code-grant: true

커스텀 CSS 스타일링

/* src/main/resources/static/swagger-ui/custom.css */

/* 전체 테마 색상 */
:root {
  --primary-color: #2c3e50;
  --secondary-color: #3498db;
  --success-color: #27ae60;
  --warning-color: #f39c12;
  --danger-color: #e74c3c;
  --light-bg: #ecf0f1;
}

/* 헤더 스타일링 */
.swagger-ui .topbar {
  background: linear-gradient(135deg, var(--primary-color), var(--secondary-color));
  border-bottom: 3px solid var(--secondary-color);
}

.swagger-ui .topbar .download-url-wrapper {
  display: none; /* URL 입력 박스 숨기기 */
}

/* 로고 추가 */
.swagger-ui .topbar::before {
  content: "";
  background-image: url('/images/company-logo.png');
  background-size: contain;
  background-repeat: no-repeat;
  width: 120px;
  height: 40px;
  display: inline-block;
  margin-right: 20px;
}

/* API 정보 섹션 */
.swagger-ui .info {
  margin: 30px 0;
  padding: 20px;
  background: var(--light-bg);
  border-radius: 8px;
  border-left: 4px solid var(--secondary-color);
}

.swagger-ui .info .title {
  color: var(--primary-color);
  font-size: 2.5em;
  font-weight: bold;
}

.swagger-ui .info .description {
  font-size: 1.1em;
  line-height: 1.6;
}

/* HTTP 메서드별 색상 */
.swagger-ui .opblock.opblock-get {
  border-color: var(--secondary-color);
  background: rgba(52, 152, 219, 0.1);
}

.swagger-ui .opblock.opblock-post {
  border-color: var(--success-color);
  background: rgba(39, 174, 96, 0.1);
}

.swagger-ui .opblock.opblock-put {
  border-color: var(--warning-color);
  background: rgba(243, 156, 18, 0.1);
}

.swagger-ui .opblock.opblock-delete {
  border-color: var(--danger-color);
  background: rgba(231, 76, 60, 0.1);
}

/* 태그 그룹 스타일링 */
.swagger-ui .opblock-tag {
  border-bottom: 2px solid #ddd;
  padding: 15px 0;
  margin: 20px 0;
}

.swagger-ui .opblock-tag small {
  background: var(--secondary-color);
  color: white;
  padding: 4px 8px;
  border-radius: 12px;
  font-size: 0.8em;
  margin-left: 10px;
}

/* 응답 코드 색상 */
.swagger-ui .responses-inner h4 {
  font-size: 1.1em;
  font-weight: bold;
}

.swagger-ui .response-col_status {
  font-weight: bold;
}

.swagger-ui .response-col_status[data-code^="2"] {
  color: var(--success-color);
}

.swagger-ui .response-col_status[data-code^="4"] {
  color: var(--warning-color);
}

.swagger-ui .response-col_status[data-code^="5"] {
  color: var(--danger-color);
}

/* 스키마 섹션 */
.swagger-ui .model-box {
  background: #f8f9fa;
  border: 1px solid #dee2e6;
  border-radius: 6px;
}

.swagger-ui .model-title {
  background: var(--primary-color);
  color: white;
  padding: 10px 15px;
  margin: 0;
  border-radius: 6px 6px 0 0;
}

/* 버튼 스타일링 */
.swagger-ui .btn {
  border-radius: 6px;
  font-weight: 500;
  transition: all 0.3s ease;
}

.swagger-ui .btn.execute {
  background: var(--secondary-color);
  border-color: var(--secondary-color);
}

.swagger-ui .btn.execute:hover {
  background: #2980b9;
  transform: translateY(-1px);
  box-shadow: 0 4px 8px rgba(0,0,0,0.1);
}

/* 다크 모드 지원 */
@media (prefers-color-scheme: dark) {
  .swagger-ui {
    filter: invert(1) hue-rotate(180deg);
  }
  
  .swagger-ui img {
    filter: invert(1) hue-rotate(180deg);
  }
}

커스텀 JavaScript 기능

/* src/main/resources/static/swagger-ui/custom.js */

// Swagger UI 로드 완료 후 실행
window.addEventListener('DOMContentLoaded', function() {
  
  // 커스텀 헤더 추가
  function addCustomHeader() {
    const topbar = document.querySelector('.swagger-ui .topbar');
    if (topbar && !document.querySelector('.custom-header')) {
      const customHeader = document.createElement('div');
      customHeader.className = 'custom-header';
      customHeader.innerHTML = `
        <div style="background: #2c3e50; color: white; padding: 10px; text-align: center;">
          <strong>🚀 E-Commerce API Documentation</strong>
          <span style="margin-left: 20px;">환경: ${getEnvironment()}</span>
          <span style="margin-left: 20px;">버전: v2.0.0</span>
        </div>
      `;
      topbar.parentNode.insertBefore(customHeader, topbar);
    }
  }

  // 환경 정보 표시
  function getEnvironment() {
    const hostname = window.location.hostname;
    if (hostname.includes('localhost') || hostname.includes('127.0.0.1')) {
      return '개발환경';
    } else if (hostname.includes('staging')) {
      return '스테이징';
    } else {
      return '운영환경';
    }
  }

  // API 응답 시간 측정
  function measureApiResponseTime() {
    const originalFetch = window.fetch;
    window.fetch = function(...args) {
      const startTime = performance.now();
      return originalFetch.apply(this, args).then(response => {
        const endTime = performance.now();
        const duration = Math.round(endTime - startTime);
        console.log(`API 응답 시간: ${duration}ms - ${args[0]}`);
        return response;
      });
    };
  }

  // 자주 사용하는 예제 데이터 자동 입력
  function addQuickFillButtons() {
    setTimeout(() => {
      const tryItOutButtons = document.querySelectorAll('.try-out__btn');
      tryItOutButtons.forEach(button => {
        if (button.textContent.includes('Try it out')) {
          button.addEventListener('click', () => {
            setTimeout(() => {
              addExampleDataButtons();
            }, 500);
          });
        }
      });
    }, 2000);
  }

  function addExampleDataButtons() {
    const textareas = document.querySelectorAll('.body-param__text');
    textareas.forEach(textarea => {
      if (!textarea.nextElementSibling?.classList.contains('example-buttons')) {
        const buttonContainer = document.createElement('div');
        buttonContainer.className = 'example-buttons';
        buttonContainer.style.marginTop = '10px';
        
        const exampleButton = document.createElement('button');
        exampleButton.textContent = '예제 데이터 입력';
        exampleButton.className = 'btn btn-sm';
        exampleButton.style.background = '#3498db';
        exampleButton.style.color = 'white';
        exampleButton.style.border = 'none';
        exampleButton.style.padding = '5px 10px';
        exampleButton.style.borderRadius = '4px';
        exampleButton.style.cursor = 'pointer';
        
        exampleButton.addEventListener('click', (e) => {
          e.preventDefault();
          fillExampleData(textarea);
        });
        
        buttonContainer.appendChild(exampleButton);
        textarea.parentNode.insertBefore(buttonContainer, textarea.nextSibling);
      }
    });
  }

  function fillExampleData(textarea) {
    const operationId = textarea.closest('.opblock')?.querySelector('.opblock-summary-operation-id')?.textContent;
    
    const examples = {
      'createUser': JSON.stringify({
        name: "홍길동",
        email: "hong@example.com",
        age: 30,
        phoneNumber: "010-1234-5678"
      }, null, 2),
      'createProduct': JSON.stringify({
        name: "iPhone 15 Pro",
        description: "최신 아이폰 모델",
        price: 1200000,
        categoryId: 1
      }, null, 2),
      'createOrder': JSON.stringify({
        items: [
          {
            productId: 1,
            quantity: 2
          }
        ],
        deliveryAddress: {
          recipient: "홍길동",
          phone: "010-1234-5678",
          address: "서울시 강남구 테헤란로 123",
          zipCode: "06234"
        }
      }, null, 2)
    };
    
    const exampleData = examples[operationId] || JSON.stringify({
      message: "예제 데이터가 없습니다."
    }, null, 2);
    
    textarea.value = exampleData;
    textarea.dispatchEvent(new Event('input', { bubbles: true }));
  }

  // 초기화 함수 실행
  addCustomHeader();
  measureApiResponseTime();
  addQuickFillButtons();
  
  // 페이지 변경 감지 (SPA 대응)
  let currentUrl = window.location.href;
  setInterval(() => {
    if (window.location.href !== currentUrl) {
      currentUrl = window.location.href;
      setTimeout(() => {
        addCustomHeader();
        addQuickFillButtons();
      }, 1000);
    }
  }, 1000);
});

단계별 구현 로드맵

문서화 표준 정의

// 팀 내 문서화 표준 예시

/**
 * API 문서화 가이드라인
 * 
 * 1. Controller 클래스
 *    - @Tag: 기능별 그룹명 (예: "User Management", "Product Catalog")
 *    - description: 해당 API 그룹의 역할과 책임 명시
 * 
 * 2. API 메서드
 *    - @Operation: summary(간단명료), description(상세설명)
 *    - @ApiResponse: 모든 가능한 HTTP 상태 코드 문서화
 *    - @Parameter: 모든 매개변수에 설명과 예제 추가
 * 
 * 3. DTO 클래스
 *    - @Schema: 클래스와 모든 필드에 적용
 *    - example: 실제 사용 가능한 예제 값
 *    - 유효성 검증 어노테이션과 일치하는 제약사항
 * 
 * 4. 네이밍 컨벤션
 *    - 한국어: 사용자 대상 설명
 *    - 영어: 기술적 용어 및 필드명
 *    - 일관된 용어 사용 (용어집 참조)
 */

@RestController
@RequestMapping("/api/v2/users")
@Tag(name = "User Management", description = "사용자 계정 관리 및 프로필 API")
@Validated
public class UserController {

    @Operation(
        summary = "사용자 목록 조회",
        description = "페이징을 지원하는 사용자 목록 조회 API입니다. " +
                     "관리자는 모든 사용자를, 일반 사용자는 공개 프로필만 조회할 수 있습니다."
    )
    @ApiResponses({
        @ApiResponse(
            responseCode = "200", 
            description = "조회 성공",
            content = @Content(schema = @Schema(implementation = PagedUserResponse.class))
        ),
        @ApiResponse(responseCode = "401", description = "인증 실패"),
        @ApiResponse(responseCode = "403", description = "권한 부족")
    })
    @SecurityRequirement(name = "Bearer Authentication")
    @GetMapping
    public ResponseEntity<PagedUserResponse> getUsers(
        @Parameter(description = "페이지 번호 (1부터 시작)", example = "1")
        @RequestParam(defaultValue = "1") @Min(1) int page,
        
        @Parameter(description = "페이지 크기 (최대 100)", example = "20")
        @RequestParam(defaultValue = "20") @Min(1) @Max(100) int size,
        
        @Parameter(description = "검색 키워드 (이름 또는 이메일)", example = "홍길동")
        @RequestParam(required = false) String keyword
    ) {
        // 구현 로직
    }
}

자주 발생하는 문제와 해결책