Update api_docs.py

api_docs.py

@@ -490,8 +490,131 @@ fetch(url)
     gr.Markdown("")
     gr.Markdown("### 응답 형식 (Response Format)")
     
-    # 성공 응답
+    # 성공 응답 테이블
     gr.Markdown("#### **성공 (200 OK)**")
+    
+    # 응답 구조를 테이블로 표시
+    if endpoint_key == "tide_level":
+        # 메타 정보 테이블
+        gr.Markdown("##### **Meta 정보**")
+        meta_table = "|필드 (Field)|타입 (Type)|설명 (Description)|\n"
+        meta_table += "|---|---|---|\n"
+        meta_table += "|`success`|`boolean`|요청 성공 여부|\n"
+        meta_table += "|`timestamp`|`string`|응답 생성 시간 (ISO 8601 형식)|\n"
+        meta_table += "|`meta.obs_post_id`|`string`|관측소 ID (요청한 station_id와 동일)|\n"
+        meta_table += "|`meta.obs_post_name`|`string`|관측소 이름|\n"
+        meta_table += "|`meta.obs_lat`|`string`|관측소 위도|\n"
+        meta_table += "|`meta.obs_lon`|`string`|관측소 경도|\n"
+        meta_table += "|`meta.data_type`|`string`|데이터 타입 (prediction/observation)|\n"
+        gr.Markdown(meta_table)
+        
+        gr.Markdown("##### **Data 정보**")
+        data_table = "|필드 (Field)|타입 (Type)|설명 (Description)|\n"
+        data_table += "|---|---|---|\n"
+        data_table += "|`data.record_time`|`string`|데이터 기록 시간 (ISO 8601)|\n"
+        data_table += "|`data.record_time_kst`|`string`|데이터 기록 시간 (KST 형식)|\n"
+        data_table += "|`data.tide_level`|`number`|**예측 조위 높이 (cm)**|\n"
+        data_table += "|`data.residual_value`|`number/null`|잔차 예측값|\n"
+        data_table += "|`data.harmonic_value`|`number`|조화 예측값|\n"
+        data_table += "|`data.data_source`|`string`|데이터 소스 (harmonic_only/combined)|\n"
+        data_table += "|`data.confidence`|`string`|예측 신뢰도 (high/medium/low)|\n"
+        data_table += "|`data.note`|`string`|추가 설명|\n"
+        data_table += "|`data.query_time`|`string`|쿼리 실행 시간|\n"
+        data_table += "|`data.matched_time_diff_seconds`|`number`|요청 시간과 데이터 시간 차이(초)|\n"
+        gr.Markdown(data_table)
+        
+    elif endpoint_key == "tide_series":
+        gr.Markdown("##### **응답 구조**")
+        series_table = "|필드 (Field)|타입 (Type)|설명 (Description)|\n"
+        series_table += "|---|---|---|\n"
+        series_table += "|`success`|`boolean`|요청 성공 여부|\n"
+        series_table += "|`meta.obs_post_id`|`string`|관측소 ID|\n"
+        series_table += "|`meta.obs_post_name`|`string`|관측소 이름|\n"
+        series_table += "|`meta.start_time`|`string`|조회 시작 시간|\n"
+        series_table += "|`meta.end_time`|`string`|조회 종료 시간|\n"
+        series_table += "|`meta.interval_minutes`|`integer`|데이터 간격(분)|\n"
+        series_table += "|`meta.total_records`|`integer`|전체 레코드 수|\n"
+        series_table += "|`data.tidal_obs`|`array`|시계열 조위 데이터 배열|\n"
+        series_table += "|`data.tidal_obs[].record_time`|`string`|기록 시간|\n"
+        series_table += "|`data.tidal_obs[].pred_tide`|`number`|예측 조위(cm)|\n"
+        series_table += "|`data.tidal_obs[].harmonic_tide`|`number`|조화 예측값|\n"
+        series_table += "|`data.tidal_obs[].residual_tide`|`number/null`|잔차 예측값|\n"
+        gr.Markdown(series_table)
+        
+    elif endpoint_key == "extremes":
+        gr.Markdown("##### **응답 구조**")
+        extremes_table = "|필드 (Field)|타입 (Type)|설명 (Description)|\n"
+        extremes_table += "|---|---|---|\n"
+        extremes_table += "|`success`|`boolean`|요청 성공 여부|\n"
+        extremes_table += "|`meta.obs_post_id`|`string`|관측소 ID|\n"
+        extremes_table += "|`meta.obs_post_name`|`string`|관측소 이름|\n"
+        extremes_table += "|`meta.date`|`string`|조회 날짜|\n"
+        extremes_table += "|`meta.include_secondary`|`boolean`|부차 만조/간조 포함 여부|\n"
+        extremes_table += "|`data.high_tides`|`array`|만조 정보 배열|\n"
+        extremes_table += "|`data.high_tides[].time`|`string`|만조 시간|\n"
+        extremes_table += "|`data.high_tides[].level`|`number`|만조 높이(cm)|\n"
+        extremes_table += "|`data.high_tides[].type`|`string`|만조 타입 (primary/secondary)|\n"
+        extremes_table += "|`data.low_tides`|`array`|간조 정보 배열|\n"
+        extremes_table += "|`data.low_tides[].time`|`string`|간조 시간|\n"
+        extremes_table += "|`data.low_tides[].level`|`number`|간조 높이(cm)|\n"
+        extremes_table += "|`data.low_tides[].type`|`string`|간조 타입 (primary/secondary)|\n"
+        gr.Markdown(extremes_table)
+        
+    elif endpoint_key == "alert":
+        gr.Markdown("##### **응답 구조**")
+        alert_table = "|필드 (Field)|타입 (Type)|설명 (Description)|\n"
+        alert_table += "|---|---|---|\n"
+        alert_table += "|`success`|`boolean`|요청 성공 여부|\n"
+        alert_table += "|`meta.obs_post_id`|`string`|관측소 ID|\n"
+        alert_table += "|`meta.obs_post_name`|`string`|관측소 이름|\n"
+        alert_table += "|`meta.check_period.start`|`string`|확인 시작 시간|\n"
+        alert_table += "|`meta.check_period.end`|`string`|확인 종료 시간|\n"
+        alert_table += "|`meta.warning_level`|`number`|주의 수위(cm)|\n"
+        alert_table += "|`meta.danger_level`|`number`|경고 수위(cm)|\n"
+        alert_table += "|`data.alert_status`|`string`|경보 상태 (SAFE/WARNING/DANGER)|\n"
+        alert_table += "|`data.max_level`|`number`|기간 중 최고 수위|\n"
+        alert_table += "|`data.max_level_time`|`string`|최고 수위 시간|\n"
+        alert_table += "|`data.warning_events`|`array`|주의 수위 초과 이벤트|\n"
+        alert_table += "|`data.danger_events`|`array`|경고 수위 초과 이벤트|\n"
+        alert_table += "|`data.recommendation`|`string`|권고 사항|\n"
+        gr.Markdown(alert_table)
+        
+    elif endpoint_key == "compare":
+        gr.Markdown("##### **응답 구조**")
+        compare_table = "|필드 (Field)|타입 (Type)|설명 (Description)|\n"
+        compare_table += "|---|---|---|\n"
+        compare_table += "|`success`|`boolean`|요청 성공 여부|\n"
+        compare_table += "|`meta.target_time`|`string`|비교 시간|\n"
+        compare_table += "|`meta.station_count`|`integer`|비교 관측소 수|\n"
+        compare_table += "|`data.comparisons`|`array`|관측소별 조위 정보 배열|\n"
+        compare_table += "|`data.comparisons[].station_id`|`string`|관측소 ID|\n"
+        compare_table += "|`data.comparisons[].station_name`|`string`|관측소 이름|\n"
+        compare_table += "|`data.comparisons[].tide_level`|`number`|조위 높이(cm)|\n"
+        compare_table += "|`data.comparisons[].data_time`|`string`|데이터 시간|\n"
+        compare_table += "|`data.statistics.max_level`|`number`|최고 조위|\n"
+        compare_table += "|`data.statistics.max_station`|`string`|최고 조위 관측소|\n"
+        compare_table += "|`data.statistics.min_level`|`number`|최저 조위|\n"
+        compare_table += "|`data.statistics.min_station`|`string`|최저 조위 관측소|\n"
+        compare_table += "|`data.statistics.avg_level`|`number`|평균 조위|\n"
+        gr.Markdown(compare_table)
+        
+    elif endpoint_key == "health":
+        gr.Markdown("##### **응답 구조**")
+        health_table = "|필드 (Field)|타입 (Type)|설명 (Description)|\n"
+        health_table += "|---|---|---|\n"
+        health_table += "|`success`|`boolean`|요청 성공 여부|\n"
+        health_table += "|`timestamp`|`string`|응답 시간|\n"
+        health_table += "|`status`|`string`|시스템 상태 (healthy/degraded/error)|\n"
+        health_table += "|`services.api_server`|`string`|API 서버 상태|\n"
+        health_table += "|`services.supabase`|`string`|Supabase 연결 상태|\n"
+        health_table += "|`services.gemini_api`|`string`|Gemini API 상태|\n"
+        health_table += "|`services.predictions`|`string`|예측 서비스 상태|\n"
+        health_table += "|`uptime`|`string`|서비스 가동 시간|\n"
+        health_table += "|`version`|`string`|API 버전|\n"
+        gr.Markdown(health_table)
+    
+    # 응답 예시 (JSON)
+    gr.Markdown("##### **응답 예시**")
     response_json = json.dumps(endpoint_info['response_example'], indent=2, ensure_ascii=False)
     gr.Markdown(f"```json\n{response_json}\n```")