Update ui.py

ui.py

@@ -12,6 +12,34 @@ from api_utils import (
     api_compare_stations,
     api_health_check
 )
+# --- API 문서 생성을 위한 헬퍼 함수 ---
+def generate_api_docs(endpoint: str, params: dict, description: str):
+    """엔드포인트별 API 문서 Markdown 및 코드 블록을 생성합니다."""
+    base_url = "https://alwaysgood-my-tide-env.hf.space"
+    query_string = "&".join([f"{key}={value}" for key, value in params.items()])
+    full_url = f'"{base_url}{endpoint}?{query_string}"'
+    
+    python_code = f"""
+import requests
+
+BASE_URL = "{base_url}"
+params = {params}
+
+response = requests.get(f"{{BASE_URL}}{endpoint}", params=params)
+
+if response.status_code == 200:
+    print(response.json())
+else:
+    print(f"Error: {{response.status_code}}")
+"""
+    with gr.Blocks():
+        gr.Markdown("---")
+        gr.Markdown(f"### 📚 API 사용법: {description}")
+        gr.Markdown("#### cURL")
+        gr.Code(language="bash", value=f"curl -X GET {full_url}", interactive=False)
+        gr.Markdown("#### Python (`requests`)")
+        gr.Code(language="python", value=python_code.strip(), interactive=False)
+
 
 def create_ui(prediction_handler, chatbot_handler):
     """Gradio UI를 생성하고 반환합니다."""
@@ -64,213 +92,147 @@ def create_ui(prediction_handler, chatbot_handler):
             
             # 3. API 탭 (새로 추가)
             with gr.TabItem("🔌 API"):
-                gr.Markdown("""
-                ## RESTful API 엔드포인트
-                실무에서 바로 사용 가능한 API 기능을 제공합니다.
-                """)
+                gr.Markdown("## RESTful API 엔드포인트\n실무에서 바로 사용 가능한 API 기능을 제공합니다.")
                 
                 with gr.Tabs():
-                    # 3-1. 현재 조위
-                    with gr.TabItem("현재 조위"):
+                    # 3-1. 특정 시간 조위
+                    with gr.TabItem("조위 조회"):
+                        gr.Markdown("#### 특정 관측소, 특정 시간의 조위 정보를 조회합니다.")
                         with gr.Row():
-                            with gr.Column():
-                                gr.Markdown("### 특정 시간 조위 조회")
-                                api1_station = gr.Dropdown(
-                                    choices=[(f"{STATION_NAMES[s]} ({s})", s) for s in STATIONS],
-                                    label="관측소",
-                                    value="DT_0001"
-                                )
-                                api1_time = gr.Textbox(
-                                    label="조회 시간 (비워두면 현재)",
-                                    placeholder="2024-12-25T15:00:00"
-                                )
-                                api1_fallback = gr.Checkbox(
-                                    label="조화 예측 폴백 사용",
-                                    value=True
-                                )
-                                api1_btn = gr.Button("조회")
-                            
-                            with gr.Column():
+                            with gr.Column(scale=1):
+                                api1_station = gr.Dropdown(choices=[(f"{STATION_NAMES[s]} ({s})", s) for s in STATIONS], label="관측소", value="DT_0001")
+                                api1_time = gr.Textbox(label="조회 시간 (비워두면 현재)", placeholder="2025-08-10T15:00:00")
+                                api1_btn = gr.Button("UI에서 테스트", variant="primary")
+                            with gr.Column(scale=2):
                                 api1_output = gr.JSON(label="API 응답")
                         
                         api1_btn.click(
-                            fn=lambda s, t, f: api_get_tide_level(s, t if t else None, f),
-                            inputs=[api1_station, api1_time, api1_fallback],
-                            outputs=api1_output,
-                            api_name="tide_level"
+                            fn=lambda s, t: api_handlers["tide_level"](s, t if t else None),
+                            inputs=[api1_station, api1_time],
+                            outputs=api1_output
                         )
-                    
+                        
+                        generate_api_docs(
+                            endpoint="/api/tide_level",
+                            params={"station_id": "DT_0001", "target_time": "2025-08-10T09:00:00"},
+                            description="특정 시간 조위 조회"
+                        )
+
                     # 3-2. 시계열 데이터
                     with gr.TabItem("시계열"):
+                        gr.Markdown("#### 지정된 기간의 시계열 조위 데이터를 조회합니다.")
                         with gr.Row():
-                            with gr.Column():
-                                gr.Markdown("### 시간대별 조위 데이터")
-                                api2_station = gr.Dropdown(
-                                    choices=[(f"{STATION_NAMES[s]} ({s})", s) for s in STATIONS],
-                                    label="관측소",
-                                    value="DT_0001"
-                                )
-                                api2_start = gr.Textbox(
-                                    label="시작 시간",
-                                    placeholder="2024-12-25T00:00:00"
-                                )
-                                api2_end = gr.Textbox(
-                                    label="종료 시간",
-                                    placeholder="2024-12-26T00:00:00"
-                                )
-                                api2_interval = gr.Number(
-                                    label="간격(분)",
-                                    value=60,
-                                    minimum=5,
-                                    maximum=360
-                                )
-                                api2_btn = gr.Button("조회")
-                            
-                            with gr.Column():
-                                api2_output = gr.JSON(label="API 응답 (공공 API 형식)")
+                            with gr.Column(scale=1):
+                                 api2_station = gr.Dropdown(choices=[(f"{STATION_NAMES[s]} ({s})", s) for s in STATIONS], label="관측소", value="DT_0001")
+                                 api2_start = gr.Textbox(label="시작 시간", placeholder="2025-08-10T00:00:00")
+                                 api2_end = gr.Textbox(label="종료 시간", placeholder="2025-08-11T00:00:00")
+                                 api2_interval = gr.Number(label="간격(분)", value=60, minimum=5)
+                                 api2_btn = gr.Button("UI에서 테스트", variant="primary")
+                            with gr.Column(scale=2):
+                                 api2_output = gr.JSON(label="API 응답 (공공 API 형식)")
                         
                         api2_btn.click(
-                            fn=lambda s, st, et, i: api_get_tide_series(
-                                s, st if st else None, et if et else None, int(i)
-                            ),
+                            fn=lambda s, st, et, i: api_handlers["tide_series"](s, st if st else None, et if et else None, int(i)),
                             inputs=[api2_station, api2_start, api2_end, api2_interval],
-                            outputs=api2_output,
-                            api_name="tide_series"
+                            outputs=api2_output
                         )
-                    
+                        
+                        generate_api_docs(
+                            endpoint="/api/tide_series",
+                            params={"station_id": "DT_0001", "start_time": "2025-08-10T00:00:00", "end_time": "2025-08-11T00:00:00"},
+                            description="기간별 시계열 데이터 조회"
+                        )
+
                     # 3-3. 만조/간조
                     with gr.TabItem("만조/간조"):
+                        gr.Markdown("#### 특정 날짜의 만조/간조 정보를 조회합니다.")
                         with gr.Row():
-                            with gr.Column():
-                                gr.Markdown("### 만조/간조 정보")
-                                api3_station = gr.Dropdown(
-                                    choices=[(f"{STATION_NAMES[s]} ({s})", s) for s in STATIONS],
-                                    label="관측소",
-                                    value="DT_0001"
-                                )
-                                api3_date = gr.Textbox(
-                                    label="날짜 (YYYY-MM-DD)",
-                                    placeholder=datetime.now().strftime("%Y-%m-%d")
-                                )
-                                api3_secondary = gr.Checkbox(
-                                    label="부차 만조/간조 포함",
-                                    value=False
-                                )
-                                api3_btn = gr.Button("조회")
-                            
-                            with gr.Column():
+                            with gr.Column(scale=1):
+                                api3_station = gr.Dropdown(choices=[(f"{STATION_NAMES[s]} ({s})", s) for s in STATIONS], label="관측소", value="DT_0001")
+                                api3_date = gr.Textbox(label="날짜 (YYYY-MM-DD)", placeholder=datetime.now().strftime("%Y-%m-%d"))
+                                api3_secondary = gr.Checkbox(label="부차 만조/간조 포함", value=False)
+                                api3_btn = gr.Button("UI에서 테스트", variant="primary")
+                            with gr.Column(scale=2):
                                 api3_output = gr.JSON(label="만조/간조 정보")
                         
                         api3_btn.click(
-                            fn=lambda s, d, sec: api_get_extremes_info(
-                                s, d if d else None, sec
-                            ),
+                            fn=lambda s, d, sec: api_handlers["extremes"](s, d if d else None, sec),
                             inputs=[api3_station, api3_date, api3_secondary],
-                            outputs=api3_output,
-                            api_name="extremes"
+                            outputs=api3_output
                         )
-                    
-                    # 3-4. 위험 수위
+                        
+                        generate_api_docs(
+                            endpoint="/api/extremes",
+                            params={"station_id": "DT_0001", "date": "2025-08-10"},
+                            description="만조/간조 정보 조회"
+                        )
+
+                    # 3-4. 위험 알림
                     with gr.TabItem("위험 알림"):
+                        gr.Markdown("#### 향후 설정된 시간 동안 위험 수위 도달 여부를 체크합니다.")
                         with gr.Row():
-                            with gr.Column():
-                                gr.Markdown("### 위험 수위 체크")
-                                api4_station = gr.Dropdown(
-                                    choices=[(f"{STATION_NAMES[s]} ({s})", s) for s in STATIONS],
-                                    label="관측소",
-                                    value="DT_0001"
-                                )
-                                api4_hours = gr.Number(
-                                    label="확인 시간(시간)",
-                                    value=24,
-                                    minimum=1,
-                                    maximum=72
-                                )
-                                api4_warning = gr.Number(
-                                    label="주의 수위(cm)",
-                                    value=700
-                                )
-                                api4_danger = gr.Number(
-                                    label="경고 수위(cm)",
-                                    value=750
-                                )
-                                api4_btn = gr.Button("체크")
-                            
-                            with gr.Column():
+                            with gr.Column(scale=1):
+                                api4_station = gr.Dropdown(choices=[(f"{STATION_NAMES[s]} ({s})", s) for s in STATIONS], label="관측소", value="DT_0001")
+                                api4_hours = gr.Number(label="확인 시간(시간)", value=24, minimum=1, maximum=72)
+                                api4_warning = gr.Number(label="주의 수위(cm)", value=700)
+                                api4_danger = gr.Number(label="경고 수위(cm)", value=750)
+                                api4_btn = gr.Button("UI에서 테스트", variant="primary")
+                            with gr.Column(scale=2):
                                 api4_output = gr.JSON(label="위험 수위 정보")
                         
                         api4_btn.click(
-                            fn=lambda s, h, w, d: api_check_tide_alert(s, int(h), w, d),
+                            fn=lambda s, h, w, d: api_handlers["alert"](s, int(h), w, d),
                             inputs=[api4_station, api4_hours, api4_warning, api4_danger],
-                            outputs=api4_output,
-                            api_name="alert"
+                            outputs=api4_output
                         )
-                    
+                        
+                        generate_api_docs(
+                            endpoint="/api/alert",
+                            params={"station_id": "DT_0001", "warning_level": 700, "danger_level": 750},
+                            description="위험 수위 체크"
+                        )
+
                     # 3-5. 관측소 비교
                     with gr.TabItem("비교"):
+                        gr.Markdown("#### 여러 관측소의 조위를 동시에 비교합니다.")
                         with gr.Row():
-                            with gr.Column():
-                                gr.Markdown("### 다중 관측소 비교")
-                                api5_stations = gr.CheckboxGroup(
-                                    choices=[(f"{STATION_NAMES[s]}", s) for s in STATIONS],
-                                    label="비교할 관측소 선택",
-                                    value=["DT_0001", "DT_0002", "DT_0003"]
-                                )
-                                api5_time = gr.Textbox(
-                                    label="비교 시간 (비워두면 현재)",
-                                    placeholder="2024-12-25T15:00:00"
-                                )
-                                api5_btn = gr.Button("비교")
-                            
-                            with gr.Column():
+                            with gr.Column(scale=1):
+                                api5_stations = gr.CheckboxGroup(choices=[(f"{STATION_NAMES[s]}", s) for s in STATIONS], label="비교할 관측소 선택", value=["DT_0001", "DT_0002", "DT_0003"])
+                                api5_time = gr.Textbox(label="비교 시간 (비워두면 현재)", placeholder="2025-08-10T15:00:00")
+                                api5_btn = gr.Button("UI에서 테스트", variant="primary")
+                            with gr.Column(scale=2):
                                 api5_output = gr.JSON(label="비교 결과")
                         
                         api5_btn.click(
-                            fn=lambda s, t: api_compare_stations(s, t if t else None),
+                            fn=lambda s, t: api_handlers["compare"](s, t if t else None),
                             inputs=[api5_stations, api5_time],
-                            outputs=api5_output,
-                            api_name="compare"
+                            outputs=api5_output
                         )
-                    
+    
+                        generate_api_docs(
+                            endpoint="/api/compare",
+                            params={"station_ids": ["DT_0001", "DT_0002"]}, # requests 라이브러리는 리스트를 올바르게 처리합니다.
+                            description="다중 관측소 비교"
+                        )
+
                     # 3-6. 상태 체크
                     with gr.TabItem("상태"):
-                        gr.Markdown("### API 및 시스템 상태")
-                        api6_btn = gr.Button("🔍 상태 확인", variant="secondary")
-                        api6_output = gr.JSON(label="시스템 상태")
+                        gr.Markdown("#### API 및 시스템의 현재 상태를 확인합니다.")
+                        with gr.Row():
+                            api6_btn = gr.Button("🔍 상태 확인", variant="secondary", scale=1)
+                            api6_output = gr.JSON(label="시스템 상태", scale=2)
                         
                         api6_btn.click(
-                            fn=api_health_check,
+                            fn=api_handlers["health"],
                             inputs=[],
-                            outputs=api6_output,
-                            api_name="health"
+                            outputs=api6_output
+                        )
+                        
+                        generate_api_docs(
+                            endpoint="/api/health",
+                            params={},
+                            description="시스템 상태 확인"
                         )
-                
-                # API 사용 안내
-                gr.Markdown("""
-                ---
-                ### 📚 API 사용 안내
-                
-                **Python 예제:**
-                ```python
-                from gradio_client import Client
-                
-                client = Client("https://your-space.hf.space/")
-                
-                # 현재 조위 조회
-                result = client.predict(
-                    "DT_0001",  # station_id
-                    "",         # time (empty = current)
-                    True,       # use_fallback
-                    api_name="/tide_level"
-                )
-                ```
-                
-                **특징:**
-                - 🔄 **조화 예측 폴백**: 최종 예측이 없을 때 자동으로 조화 예측 사용
-                - 📊 **공공 API 호환**: 기상청 API와 유사한 응답 형식
-                - ⚠️ **위험 수위 알림**: 2단계 경보 시스템
-                - 🏢 **다중 관측소**: 여러 관측소 동시 비교
-                """)
         
         # 이벤트 핸들러 연결
         predict_btn.click(