feat: Bypass API 화면 개선 및 Swagger 그룹 분리 (#63)

프론트엔드:
- DTO 필드 입력 폼에 필드 번호(#N) 및 총 카운트 표시
- List View(테이블 뷰) 추가 및 카드/테이블 뷰 전환
- 실시간 검색 기능 추가 (도메인명, 표시명)

Swagger:
- GroupedOpenApi로 그룹 분리 (Batch Management, Bypass Config, Bypass API)
- 코드 생성 시 @Tag에 WebClient 종류 접두사 추가
- 코드 생성 시 @Parameter에 example 기본값 설정

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

frontend/src/components/bypass/BypassStepFields.tsx

@@ -110,9 +110,15 @@ export default function BypassStepFields({ fields, onChange }: BypassStepFieldsP
                         </div>
                     ) : (
                         <div className="overflow-x-auto">
+                            <div className="mb-2 flex items-center justify-between">
+                                <span className="text-xs text-wing-muted">
+                                    총 <span className="font-semibold text-wing-text">{fields.length}</span>개 필드
+                                </span>
+                            </div>
                             <table className="w-full text-sm">
                                 <thead>
                                     <tr className="border-b border-wing-border">
+                                        <th className="pb-2 text-left font-medium text-wing-muted pr-3 w-10">#</th>
                                         <th className="pb-2 text-left font-medium text-wing-muted pr-3 min-w-[130px]">필드명</th>
                                         <th className="pb-2 text-left font-medium text-wing-muted pr-3 min-w-[130px]">JSON Property</th>
                                         <th className="pb-2 text-left font-medium text-wing-muted pr-3 min-w-[150px]">타입</th>
@@ -123,6 +129,11 @@ export default function BypassStepFields({ fields, onChange }: BypassStepFieldsP
                                 <tbody className="divide-y divide-wing-border">
                                     {fields.map((field, index) => (
                                         <tr key={index} className="group">
+                                            <td className="py-2 pr-3">
+                                                <span className="text-xs font-medium text-wing-muted tabular-nums">
+                                                    #{index + 1}
+                                                </span>
+                                            </td>
                                             <td className="py-2 pr-3">
                                                 <input
                                                     type="text"

frontend/src/pages/BypassConfig.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useMemo } from 'react';
 import {
     bypassApi,
     type BypassConfigRequest,
@@ -17,6 +17,8 @@ interface ConfirmAction {
     config: BypassConfigResponse;
 }
 
+type ViewMode = 'card' | 'table';
+
 const HTTP_METHOD_COLORS: Record<string, string> = {
     GET: 'bg-emerald-100 text-emerald-700',
     POST: 'bg-blue-100 text-blue-700',
@@ -30,6 +32,8 @@ export default function BypassConfig() {
     const [configs, setConfigs] = useState<BypassConfigResponse[]>([]);
     const [loading, setLoading] = useState(true);
     const [webclientBeans, setWebclientBeans] = useState<WebClientBeanInfo[]>([]);
+    const [viewMode, setViewMode] = useState<ViewMode>('card');
+    const [searchTerm, setSearchTerm] = useState('');
 
     const [modalOpen, setModalOpen] = useState(false);
     const [editConfig, setEditConfig] = useState<BypassConfigResponse | null>(null);
@@ -106,6 +110,16 @@ export default function BypassConfig() {
         }
     };
 
+    const filteredConfigs = useMemo(() => {
+        if (!searchTerm.trim()) return configs;
+        const term = searchTerm.toLowerCase();
+        return configs.filter(
+            (c) =>
+                c.domainName.toLowerCase().includes(term) ||
+                c.displayName.toLowerCase().includes(term),
+        );
+    }, [configs, searchTerm]);
+
     if (loading) return <LoadingSpinner />;
 
     return (
@@ -127,15 +141,102 @@ export default function BypassConfig() {
                 </button>
             </div>
 
-            {/* 카드 그리드 */}
+            {/* 검색 + 뷰 전환 */}
+            <div className="bg-wing-surface rounded-xl shadow-md p-4">
+                <div className="flex gap-3 items-center flex-wrap">
+                    {/* 검색 */}
+                    <div className="relative flex-1 min-w-[200px]">
+                        <span className="absolute inset-y-0 left-3 flex items-center text-wing-muted">
+                            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                <path
+                                    strokeLinecap="round"
+                                    strokeLinejoin="round"
+                                    strokeWidth={2}
+                                    d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+                                />
+                            </svg>
+                        </span>
+                        <input
+                            type="text"
+                            placeholder="도메인명, 표시명으로 검색..."
+                            value={searchTerm}
+                            onChange={(e) => setSearchTerm(e.target.value)}
+                            className="w-full pl-10 pr-4 py-2 border border-wing-border rounded-lg text-sm
+                                focus:ring-2 focus:ring-wing-accent focus:border-wing-accent outline-none bg-wing-surface text-wing-text"
+                        />
+                        {searchTerm && (
+                            <button
+                                type="button"
+                                onClick={() => setSearchTerm('')}
+                                className="absolute inset-y-0 right-3 flex items-center text-wing-muted hover:text-wing-text"
+                            >
+                                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+                                </svg>
+                            </button>
+                        )}
+                    </div>
+
+                    {/* 뷰 전환 토글 */}
+                    <div className="flex rounded-lg border border-wing-border overflow-hidden">
+                        <button
+                            type="button"
+                            onClick={() => setViewMode('table')}
+                            title="테이블 보기"
+                            className={`px-3 py-2 transition-colors ${
+                                viewMode === 'table'
+                                    ? 'bg-wing-accent text-white'
+                                    : 'bg-wing-surface text-wing-muted hover:text-wing-text'
+                            }`}
+                        >
+                            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6h16M4 12h16M4 18h16" />
+                            </svg>
+                        </button>
+                        <button
+                            type="button"
+                            onClick={() => setViewMode('card')}
+                            title="카드 보기"
+                            className={`px-3 py-2 transition-colors border-l border-wing-border ${
+                                viewMode === 'card'
+                                    ? 'bg-wing-accent text-white'
+                                    : 'bg-wing-surface text-wing-muted hover:text-wing-text'
+                            }`}
+                        >
+                            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                <path
+                                    strokeLinecap="round"
+                                    strokeLinejoin="round"
+                                    strokeWidth={2}
+                                    d="M4 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2V6zM14 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2V6zM4 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2v-2zM14 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2v-2z"
+                                />
+                            </svg>
+                        </button>
+                    </div>
+                </div>
+
+                {searchTerm && (
+                    <p className="mt-2 text-xs text-wing-muted">
+                        {filteredConfigs.length}개 API 검색됨
+                    </p>
+                )}
+            </div>
+
+            {/* 빈 상태 */}
             {configs.length === 0 ? (
                 <div className="py-16 text-center text-wing-muted border border-dashed border-wing-border rounded-xl bg-wing-card">
                     <p className="text-base font-medium mb-1">등록된 BYPASS API가 없습니다.</p>
                     <p className="text-sm">위 버튼을 눌러 새 API를 등록하세요.</p>
                 </div>
-            ) : (
+            ) : filteredConfigs.length === 0 ? (
+                <div className="py-16 text-center text-wing-muted border border-dashed border-wing-border rounded-xl bg-wing-card">
+                    <p className="text-base font-medium mb-1">검색 결과가 없습니다.</p>
+                    <p className="text-sm">다른 검색어를 사용해 보세요.</p>
+                </div>
+            ) : viewMode === 'card' ? (
+                /* 카드 뷰 */
                 <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-                    {configs.map((config) => (
+                    {filteredConfigs.map((config) => (
                         <div
                             key={config.id}
                             className="bg-wing-card border border-wing-border rounded-xl p-5 flex flex-col gap-3 hover:border-wing-accent/40 transition-colors"
@@ -209,6 +310,112 @@ export default function BypassConfig() {
                         </div>
                     ))}
                 </div>
+            ) : (
+                /* 테이블 뷰 */
+                <div className="bg-wing-surface rounded-xl shadow-md overflow-hidden">
+                    <div className="overflow-x-auto">
+                        <table className="w-full text-sm">
+                            <thead>
+                                <tr className="border-b border-wing-border bg-wing-card">
+                                    <th className="text-left px-4 py-3 text-xs font-semibold text-wing-muted uppercase tracking-wider">
+                                        도메인명
+                                    </th>
+                                    <th className="text-left px-4 py-3 text-xs font-semibold text-wing-muted uppercase tracking-wider">
+                                        표시명
+                                    </th>
+                                    <th className="text-left px-4 py-3 text-xs font-semibold text-wing-muted uppercase tracking-wider">
+                                        HTTP 메서드
+                                    </th>
+                                    <th className="text-left px-4 py-3 text-xs font-semibold text-wing-muted uppercase tracking-wider">
+                                        WebClient
+                                    </th>
+                                    <th className="text-left px-4 py-3 text-xs font-semibold text-wing-muted uppercase tracking-wider">
+                                        외부 경로
+                                    </th>
+                                    <th className="text-left px-4 py-3 text-xs font-semibold text-wing-muted uppercase tracking-wider">
+                                        생성 상태
+                                    </th>
+                                    <th className="text-left px-4 py-3 text-xs font-semibold text-wing-muted uppercase tracking-wider">
+                                        등록일
+                                    </th>
+                                    <th className="text-right px-4 py-3 text-xs font-semibold text-wing-muted uppercase tracking-wider">
+                                        액션
+                                    </th>
+                                </tr>
+                            </thead>
+                            <tbody className="divide-y divide-wing-border">
+                                {filteredConfigs.map((config) => (
+                                    <tr key={config.id} className="hover:bg-wing-hover transition-colors">
+                                        <td className="px-4 py-3 font-mono text-xs text-wing-text">
+                                            {config.domainName}
+                                        </td>
+                                        <td className="px-4 py-3 font-medium text-wing-text">
+                                            {config.displayName}
+                                        </td>
+                                        <td className="px-4 py-3">
+                                            <span
+                                                className={[
+                                                    'px-2 py-0.5 text-xs font-bold rounded',
+                                                    HTTP_METHOD_COLORS[config.httpMethod] ?? 'bg-wing-card text-wing-muted',
+                                                ].join(' ')}
+                                            >
+                                                {config.httpMethod}
+                                            </span>
+                                        </td>
+                                        <td className="px-4 py-3 text-xs text-wing-muted">
+                                            {config.webclientBean}
+                                        </td>
+                                        <td className="px-4 py-3 font-mono text-xs text-wing-muted max-w-[200px] truncate">
+                                            {config.externalPath}
+                                        </td>
+                                        <td className="px-4 py-3">
+                                            <span
+                                                className={[
+                                                    'px-2 py-0.5 text-xs font-semibold rounded-full',
+                                                    config.generated
+                                                        ? 'bg-emerald-100 text-emerald-700'
+                                                        : 'bg-wing-card text-wing-muted border border-wing-border',
+                                                ].join(' ')}
+                                            >
+                                                {config.generated ? '생성 완료' : '미생성'}
+                                            </span>
+                                        </td>
+                                        <td className="px-4 py-3 text-xs text-wing-muted whitespace-nowrap">
+                                            {config.createdAt
+                                                ? new Date(config.createdAt).toLocaleDateString('ko-KR')
+                                                : '-'}
+                                        </td>
+                                        <td className="px-4 py-3">
+                                            <div className="flex justify-end gap-2">
+                                                <button
+                                                    type="button"
+                                                    onClick={() => handleEdit(config)}
+                                                    className="px-3 py-1.5 text-xs font-medium text-wing-text bg-wing-card hover:bg-wing-hover border border-wing-border rounded-lg transition-colors"
+                                                >
+                                                    수정
+                                                </button>
+                                                <button
+                                                    type="button"
+                                                    onClick={() => setConfirmAction({ type: 'generate', config })}
+                                                    className="px-3 py-1.5 text-xs font-medium text-white bg-wing-accent hover:bg-wing-accent/80 rounded-lg transition-colors"
+                                                >
+                                                    {config.generated ? '재생성' : '코드 생성'}
+                                                </button>
+                                                <button
+                                                    type="button"
+                                                    onClick={() => setConfirmAction({ type: 'delete', config })}
+                                                    className="px-3 py-1.5 text-xs font-medium text-red-500 hover:bg-red-50 border border-red-200 rounded-lg transition-colors"
+                                                >
+                                                    삭제
+                                                </button>
+                                            </div>
+                                        </td>
+                                    </tr>
+                                ))}
+                            </tbody>
+                        </table>
+                    </div>
+                </div>
             )}
 
             {/* 등록/수정 모달 */}

src/main/java/com/snp/batch/global/config/SwaggerConfig.java

@@ -5,6 +5,7 @@ import io.swagger.v3.oas.models.info.Contact;
 import io.swagger.v3.oas.models.info.Info;
 import io.swagger.v3.oas.models.info.License;
 import io.swagger.v3.oas.models.servers.Server;
+import org.springdoc.core.models.GroupedOpenApi;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -33,6 +34,31 @@ public class SwaggerConfig {
     @Value("${server.servlet.context-path:}")
     private String contextPath;
 
+    @Bean
+    public GroupedOpenApi batchManagementApi() {
+        return GroupedOpenApi.builder()
+                .group("1. Batch Management")
+                .pathsToMatch("/api/batch/**")
+                .build();
+    }
+
+    @Bean
+    public GroupedOpenApi bypassConfigApi() {
+        return GroupedOpenApi.builder()
+                .group("2. Bypass Config")
+                .pathsToMatch("/api/bypass-config/**")
+                .build();
+    }
+
+    @Bean
+    public GroupedOpenApi bypassApi() {
+        return GroupedOpenApi.builder()
+                .group("3. Bypass API")
+                .pathsToMatch("/api/**")
+                .pathsToExclude("/api/batch/**", "/api/bypass-config/**")
+                .build();
+    }
+
     @Bean
     public OpenAPI openAPI() {
         return new OpenAPI()

src/main/java/com/snp/batch/jobs/web/risk/controller/RiskController.java

@@ -23,7 +23,7 @@ import java.util.List;
 @RestController
 @RequestMapping("/api/risk")
 @RequiredArgsConstructor
-@Tag(name = "Risk", description = "선박 Risk 상세 정보 bypass API")
+@Tag(name = "Risk", description = "[Service API] 선박 Risk 상세 정보 bypass API")
 public class RiskController extends BaseBypassController {
 
     private final RiskBypassService riskBypassService;

src/main/java/com/snp/batch/service/BypassCodeGenerator.java

@@ -232,7 +232,7 @@ public class BypassCodeGenerator {
                 @RestController
                 @RequestMapping("{{REQUEST_MAPPING_PATH}}")
                 @RequiredArgsConstructor
-                @Tag(name = "{{DOMAIN_CAP}}", description = "{{DISPLAY_NAME}} bypass API")
+                @Tag(name = "{{DOMAIN_CAP}}", description = "{{TAG_PREFIX}} {{DISPLAY_NAME}} bypass API")
                 public class {{DOMAIN_CAP}}Controller extends BaseBypassController {
 
                     private final {{SERVICE_CLASS}} {{SERVICE_FIELD}};
@@ -255,6 +255,7 @@ public class BypassCodeGenerator {
                 .replace("{{REQUEST_PARAM_IMPORT}}", requestParamImport)
                 .replace("{{REQUEST_BODY_IMPORT}}", requestBodyImport)
                 .replace("{{MAPPING_IMPORT}}", mappingImport)
+                .replace("{{TAG_PREFIX}}", getTagPrefix(config.getWebclientBean()))
                 .replace("{{DISPLAY_NAME}}", config.getDisplayName())
                 .replace("{{DOMAIN_CAP}}", domainCap)
                 .replace("{{REQUEST_MAPPING_PATH}}", requestMappingPath)
@@ -331,14 +332,15 @@ public class BypassCodeGenerator {
                     String description = p.getDescription() != null ? p.getDescription() : p.getParamName();
                     String javaType = toJavaType(p.getParamType());
                     String paramName = p.getParamName();
+                    String example = getDefaultExample(p.getParamType());
                     return switch (p.getParamIn().toUpperCase()) {
-                        case "PATH" -> "@Parameter(description = \"" + description + "\")\n"
+                        case "PATH" -> "@Parameter(description = \"" + description + "\", example = \"" + example + "\")\n"
                                 + "                @PathVariable " + javaType + " " + paramName;
-                        case "BODY" -> "@Parameter(description = \"" + description + "\")\n"
+                        case "BODY" -> "@Parameter(description = \"" + description + "\", example = \"" + example + "\")\n"
                                 + "                @RequestBody " + javaType + " " + paramName;
                         default -> {
                             String required = Boolean.TRUE.equals(p.getRequired()) ? "true" : "false";
-                            yield "@Parameter(description = \"" + description + "\")\n"
+                            yield "@Parameter(description = \"" + description + "\", example = \"" + example + "\")\n"
                                     + "                @RequestParam(required = " + required + ") " + javaType + " " + paramName;
                         }
                     };
@@ -401,6 +403,35 @@ public class BypassCodeGenerator {
         return filePath;
     }
 
+    /**
+     * webclientBean 이름 → Swagger @Tag description 접두사 변환
+     */
+    private String getTagPrefix(String webclientBean) {
+        if (webclientBean == null) {
+            return "[Ship API]";
+        }
+        return switch (webclientBean) {
+            case "maritimeAisApiWebClient" -> "[AIS API]";
+            case "maritimeServiceApiWebClient" -> "[Service API]";
+            default -> "[Ship API]";
+        };
+    }
+
+    /**
+     * paramType → Swagger @Parameter example 기본값 결정
+     */
+    private String getDefaultExample(String paramType) {
+        if (paramType == null) {
+            return "9876543";
+        }
+        return switch (paramType.toUpperCase()) {
+            case "INTEGER" -> "0";
+            case "LONG" -> "0";
+            case "BOOLEAN" -> "true";
+            default -> "9876543";
+        };
+    }
+
     private String capitalize(String s) {
         if (s == null || s.isEmpty()) {
             return s;