Create api_docs.py

api_docs.py

@@ -0,0 +1,514 @@
+"""
+API 문서 생성 모듈
+API 엔드포인트 정보와 문서 생성 함수를 포함합니다.
+"""
+
+import gradio as gr
+import json
+
+# API 엔드포인트별 상세 정보 정의
+API_ENDPOINTS = {
+    "tide_level": {
+        "path": "/api/tide_level",
+        "title": "특정 시간 조위 조회",
+        "description": "지정한 관측소(`station_id`)의 특정 시간(`target_time`)에 대한 예측 조위 정보를 반환합니다. `target_time`을 지정하지 않으면 현재 시간에 가장 가까운 데이터를 반환합니다.",
+        "parameters": [
+            {"name": "station_id", "type": "string", "required": True, "description": "조회할 관측소의 고유 ID입니다. (예: 'DT_0001')"},
+            {"name": "target_time", "type": "string", "required": False, "description": "조회할 시간입니다. ISO 8601 형식(YYYY-MM-DDTHH:MM:SS)을 권장하며, 생략 시 현재 시간으로 자동 설정됩니다."}
+        ],
+        "example_params": {"station_id": "DT_0001", "target_time": "2025-08-10T09:00:00"},
+        "example_params_current": {"station_id": "DT_0001"},
+        "response_example": {
+            "success": True,
+            "timestamp": "2025-08-10T00:23:00.394870+09:00",
+            "meta": {
+                "obs_post_id": "DT_0001",
+                "obs_post_name": "인천",
+                "obs_lat": "37.452",
+                "obs_lon": "126.592",
+                "data_type": "prediction"
+            },
+            "data": {
+                "record_time": "2025-08-10T00:20:00+09:00",
+                "record_time_kst": "2025-08-10 00:20:00 KST",
+                "final_value": 138.8,
+                "residual_value": None,
+                "harmonic_value": 138.8,
+                "data_source": "harmonic_only",
+                "confidence": "medium",
+                "note": "잔차 예측이 없어 조화 예측만 제공됩니다",
+                "query_time": "2025-08-10 00:22:57 KST",
+                "matched_time_diff_seconds": 177.78439
+            }
+        }
+    },
+    "tide_series": {
+        "path": "/api/tide_series",
+        "title": "시계열 조위 데이터 조회",
+        "description": "지정된 기간 동안의 시계열 조위 데이터를 조회합니다. 공공 API와 유사한 형식으로 반환되며, 간격(interval)을 지정할 수 있습니다.",
+        "parameters": [
+            {"name": "station_id", "type": "string", "required": True, "description": "조회할 관측소의 고유 ID입니다."},
+            {"name": "start_time", "type": "string", "required": False, "description": "조회 시작 시간입니다. 생략 시 현재 시간부터 시작합니다."},
+            {"name": "end_time", "type": "string", "required": False, "description": "조회 종료 시간입니다. 생략 시 시작 시간으로부터 24시간 후까지 조회합니다."},
+            {"name": "interval", "type": "integer", "required": False, "description": "데이터 간격(분 단위). 기본값: 60분, 최소값: 5분"}
+        ],
+        "example_params": {"station_id": "DT_0001", "start_time": "2025-08-10T00:00:00", "end_time": "2025-08-11T00:00:00", "interval": 60},
+        "response_example": {
+            "success": True,
+            "timestamp": "2025-08-10T00:30:00.123456+09:00",
+            "meta": {
+                "obs_post_id": "DT_0001",
+                "obs_post_name": "인천",
+                "start_time": "2025-08-10T00:00:00+09:00",
+                "end_time": "2025-08-11T00:00:00+09:00",
+                "interval_minutes": 60,
+                "total_records": 25
+            },
+            "data": {
+                "tidal_obs": [
+                    {
+                        "record_time": "2025-08-10 00:00",
+                        "pred_tide": 125.3,
+                        "harmonic_tide": 125.3,
+                        "residual_tide": None
+                    },
+                    {
+                        "record_time": "2025-08-10 01:00",
+                        "pred_tide": 142.7,
+                        "harmonic_tide": 142.7,
+                        "residual_tide": None
+                    }
+                ]
+            }
+        }
+    },
+    "extremes": {
+        "path": "/api/extremes",
+        "title": "만조/간조 정보 조회",
+        "description": "특정 날짜의 만조(high tide)와 간조(low tide) 정보를 조회합니다. 주요 만조/간조와 부차 만조/간조를 구분하여 제공합니다.",
+        "parameters": [
+            {"name": "station_id", "type": "string", "required": True, "description": "조회할 관측소의 고유 ID입니다."},
+            {"name": "date", "type": "string", "required": False, "description": "조회할 날짜 (YYYY-MM-DD 형식). 생략 시 오늘 날짜로 설정됩니다."},
+            {"name": "include_secondary", "type": "boolean", "required": False, "description": "부차 만조/간조 포함 여부. 기본값: false"}
+        ],
+        "example_params": {"station_id": "DT_0001", "date": "2025-08-10", "include_secondary": True},
+        "response_example": {
+            "success": True,
+            "timestamp": "2025-08-10T00:35:00.123456+09:00",
+            "meta": {
+                "obs_post_id": "DT_0001",
+                "obs_post_name": "인천",
+                "date": "2025-08-10",
+                "include_secondary": True
+            },
+            "data": {
+                "high_tides": [
+                    {
+                        "time": "2025-08-10T06:15:00+09:00",
+                        "time_kst": "2025-08-10 06:15:00 KST",
+                        "level": 812.5,
+                        "type": "primary"
+                    },
+                    {
+                        "time": "2025-08-10T18:45:00+09:00",
+                        "time_kst": "2025-08-10 18:45:00 KST",
+                        "level": 798.3,
+                        "type": "primary"
+                    }
+                ],
+                "low_tides": [
+                    {
+                        "time": "2025-08-10T00:30:00+09:00",
+                        "time_kst": "2025-08-10 00:30:00 KST",
+                        "level": 98.2,
+                        "type": "primary"
+                    },
+                    {
+                        "time": "2025-08-10T12:45:00+09:00",
+                        "time_kst": "2025-08-10 12:45:00 KST",
+                        "level": 112.7,
+                        "type": "primary"
+                    }
+                ]
+            }
+        }
+    },
+    "alert": {
+        "path": "/api/alert",
+        "title": "위험 수위 체크",
+        "description": "향후 지정된 시간 동안 주의 수위 또는 경고 수위에 도달하는지 확인합니다. 위험 시점과 예상 수위를 반환합니다.",
+        "parameters": [
+            {"name": "station_id", "type": "string", "required": True, "description": "체크할 관측소의 고유 ID입니다."},
+            {"name": "hours_ahead", "type": "integer", "required": False, "description": "확인할 시간 범위(시간 단위). 기본값: 24시간, 최대: 72시간"},
+            {"name": "warning_level", "type": "number", "required": False, "description": "주의 수위(cm). 기본값: 700cm"},
+            {"name": "danger_level", "type": "number", "required": False, "description": "경고 수위(cm). 기본값: 750cm"}
+        ],
+        "example_params": {"station_id": "DT_0001", "hours_ahead": 24, "warning_level": 700, "danger_level": 750},
+        "response_example": {
+            "success": True,
+            "timestamp": "2025-08-10T00:40:00.123456+09:00",
+            "meta": {
+                "obs_post_id": "DT_0001",
+                "obs_post_name": "인천",
+                "check_period": {
+                    "start": "2025-08-10T00:40:00+09:00",
+                    "end": "2025-08-11T00:40:00+09:00"
+                },
+                "warning_level": 700,
+                "danger_level": 750
+            },
+            "data": {
+                "alert_status": "DANGER",
+                "max_level": 812.5,
+                "max_level_time": "2025-08-10T06:15:00+09:00",
+                "warning_events": [
+                    {
+                        "time": "2025-08-10T05:30:00+09:00",
+                        "level": 702.3,
+                        "type": "warning_exceeded"
+                    }
+                ],
+                "danger_events": [
+                    {
+                        "time": "2025-08-10T06:00:00+09:00",
+                        "level": 755.8,
+                        "type": "danger_exceeded"
+                    }
+                ],
+                "recommendation": "경고 수위 초과 예상. 해안가 접근 주의 필요"
+            }
+        }
+    },
+    "compare": {
+        "path": "/api/compare",
+        "title": "다중 관측소 비교",
+        "description": "여러 관측소의 조위를 동시에 비교합니다. 지정한 시간의 각 관측소별 조위 정보를 한 번에 조회할 수 있습니다.",
+        "parameters": [
+            {"name": "station_ids", "type": "array", "required": True, "description": "비교할 관측소 ID 목록 (배열 형태). 예: ['DT_0001', 'DT_0002']"},
+            {"name": "target_time", "type": "string", "required": False, "description": "비교할 시간. 생략 시 현재 시간으로 설정됩니다."}
+        ],
+        "example_params": {"station_ids": ["DT_0001", "DT_0002", "DT_0003"], "target_time": "2025-08-10T09:00:00"},
+        "response_example": {
+            "success": True,
+            "timestamp": "2025-08-10T00:45:00.123456+09:00",
+            "meta": {
+                "target_time": "2025-08-10T09:00:00+09:00",
+                "station_count": 3
+            },
+            "data": {
+                "comparisons": [
+                    {
+                        "station_id": "DT_0001",
+                        "station_name": "인천",
+                        "tide_level": 425.3,
+                        "data_time": "2025-08-10T09:00:00+09:00"
+                    },
+                    {
+                        "station_id": "DT_0002",
+                        "station_name": "안흥",
+                        "tide_level": 312.8,
+                        "data_time": "2025-08-10T09:00:00+09:00"
+                    },
+                    {
+                        "station_id": "DT_0003",
+                        "station_name": "보령",
+                        "tide_level": 298.5,
+                        "data_time": "2025-08-10T09:00:00+09:00"
+                    }
+                ],
+                "statistics": {
+                    "max_level": 425.3,
+                    "max_station": "인천",
+                    "min_level": 298.5,
+                    "min_station": "보령",
+                    "avg_level": 345.5
+                }
+            }
+        }
+    },
+    "health": {
+        "path": "/api/health",
+        "title": "시스템 상태 확인",
+        "description": "API 서버 및 연결된 시스템의 상태를 확인합니다. 데이터베이스 연결, API 키 설정 등을 점검합니다.",
+        "parameters": [],
+        "example_params": {},
+        "response_example": {
+            "success": True,
+            "timestamp": "2025-08-10T00:50:00.123456+09:00",
+            "status": "healthy",
+            "services": {
+                "api_server": "running",
+                "supabase": "connected",
+                "gemini_api": "configured",
+                "predictions": "available"
+            },
+            "uptime": "2 hours 15 minutes",
+            "version": "1.0.0"
+        }
+    }
+}
+
+
+def copy_to_clipboard(text):
+    """클립보드에 텍스트 복사 (JavaScript 실행)"""
+    return f"""
+    <script>
+    navigator.clipboard.writeText('{text}');
+    alert('URL이 클립보드에 복사되었습니다!');
+    </script>
+    """
+
+
+def generate_api_docs(endpoint_key: str):
+    """엔드포인트별 상세 API 문서를 생성합니다."""
+    
+    base_url = "https://alwaysgood-my-tide-env.hf.space"
+    endpoint_info = API_ENDPOINTS[endpoint_key]
+    
+    # 섹션 제목
+    gr.Markdown("---")
+    gr.Markdown(f"## 📚 API 사용 안내서")
+    gr.Markdown(f"### `{endpoint_info['path']}` : {endpoint_info['title']}")
+    gr.Markdown(endpoint_info['description'])
+    
+    # 기본 정보
+    gr.Markdown("- **Method**: `GET`")
+    gr.Markdown(f"- **URL**: `{base_url}{endpoint_info['path']}`")
+    gr.Markdown("")
+    
+    # 요청 파라미터 테이블
+    if endpoint_info['parameters']:
+        gr.Markdown("### 요청 파라미터 (Query Parameters)")
+        
+        # 테이블 헤더
+        table_md = "|파라미터 (Parameter)|타입 (Type)|필수 (Required)|설명 (Description)|\n"
+        table_md += "|---|---|---|---|\n"
+        
+        # 파라미터 정보
+        for param in endpoint_info['parameters']:
+            required_text = "**Yes**" if param['required'] else "No"
+            table_md += f"|`{param['name']}`|`{param['type']}`|{required_text}|{param['description']}|\n"
+        
+        gr.Markdown(table_md)
+        gr.Markdown("")
+    
+    # 사용 예시
+    gr.Markdown("### 사용 예시 (Usage Examples)")
+    
+    # Python 예시
+    python_code = f'''import requests
+import json
+
+BASE_URL = "{base_url}"
+'''
+    
+    # 엔드포인트별 특별 처리
+    if endpoint_key == "tide_level":
+        python_code += f'''
+# 1. 현재 조위 조회 (인천 관측소)
+params_now = {{
+    "station_id": "DT_0001"
+}}
+
+response_now = requests.get(f"{{BASE_URL}}{endpoint_info['path']}", params=params_now)
+print("--- 현재 조위 조회 결과 ---")
+print(response_now.json())
+
+# 2. 특정 시간 조위 조회 (2025년 8월 10일 오전 9시)
+params_specific_time = {{
+    "station_id": "DT_0001",
+    "target_time": "2025-08-10T09:00:00"
+}}
+
+response_specific = requests.get(f"{{BASE_URL}}{endpoint_info['path']}", params=params_specific_time)
+print("\\n--- 특정 시간 조위 조회 결과 ---")
+print(response_specific.json())'''
+    
+    elif endpoint_key == "compare":
+        python_code += f'''
+# 여러 관측소 동시 비교
+params = {{
+    "station_ids": ["DT_0001", "DT_0002", "DT_0003"],
+    "target_time": "2025-08-10T09:00:00"
+}}
+
+response = requests.get(f"{{BASE_URL}}{endpoint_info['path']}", params=params)
+
+if response.status_code == 200:
+    data = response.json()
+    print("--- 관측소별 조위 비교 ---")
+    for station in data['data']['comparisons']:
+        print(f"{{station['station_name']}}: {{station['tide_level']}}cm")
+else:
+    print(f"Error: {{response.status_code}}")'''
+    
+    elif endpoint_key == "health":
+        python_code += f'''
+# 시스템 상태 확인
+response = requests.get(f"{{BASE_URL}}{endpoint_info['path']}")
+
+if response.status_code == 200:
+    data = response.json()
+    print(f"시스템 상태: {{data['status']}}")
+    print(f"서비스 상태: {{data['services']}}")
+else:
+    print(f"Error: {{response.status_code}}")'''
+    
+    else:
+        # 일반적인 경우
+        python_code += f'''
+# 요청 파라미터 설정
+params = {json.dumps(endpoint_info['example_params'], indent=4, ensure_ascii=False)}
+
+response = requests.get(f"{{BASE_URL}}{endpoint_info['path']}", params=params)
+
+if response.status_code == 200:
+    data = response.json()
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+else:
+    print(f"Error: {{response.status_code}}")'''
+    
+    gr.Markdown("#### **Python (`requests` 사용)**")
+    gr.Markdown(f"```python\n{python_code.strip()}\n```")
+    
+    # curl 예시
+    # URL 파라미터 생성
+    if endpoint_key == "compare":
+        # 배열 파라미터는 특별 처리
+        curl_params = "&".join([f"station_ids={sid}" for sid in endpoint_info['example_params']['station_ids']])
+        if 'target_time' in endpoint_info['example_params']:
+            curl_params += f"&target_time={endpoint_info['example_params']['target_time']}"
+    elif endpoint_key == "health":
+        curl_params = ""
+    else:
+        curl_params = "&".join([f"{k}={v}" for k, v in endpoint_info['example_params'].items()])
+    
+    curl_url = f"{base_url}{endpoint_info['path']}"
+    if curl_params:
+        curl_url += f"?{curl_params}"
+    
+    curl_code = f'# 요청 예시\ncurl -X GET "{curl_url}"'
+    
+    # 특별 케이스 추가
+    if endpoint_key == "tide_level":
+        curl_code = f'''# 현재 조위 조회
+curl -X GET "{base_url}{endpoint_info['path']}?station_id=DT_0001"
+
+# 특정 시간 조위 조회
+curl -X GET "{base_url}{endpoint_info['path']}?station_id=DT_0001&target_time=2025-08-10T09:00:00"'''
+    
+    gr.Markdown("#### **curl (Command Line)**")
+    gr.Markdown(f"```bash\n{curl_code}\n```")
+    
+    # JavaScript 예시
+    if endpoint_key == "compare":
+        js_code = f'''const stationIds = ['DT_0001', 'DT_0002', 'DT_0003'];
+const params = new URLSearchParams();
+stationIds.forEach(id => params.append('station_ids', id));
+params.append('target_time', '2025-08-10T09:00:00');
+
+const url = `{base_url}{endpoint_info['path']}?${{params}}`;
+
+fetch(url)
+    .then(response => response.json())
+    .then(data => {{
+        console.log('비교 결과:', data);
+        data.data.comparisons.forEach(station => {{
+            console.log(`${{station.station_name}}: ${{station.tide_level}}cm`);
+        }});
+    }})
+    .catch(error => {{
+        console.error('Error:', error);
+    }});'''
+    
+    elif endpoint_key == "health":
+        js_code = f'''const url = '{base_url}{endpoint_info['path']}';
+
+fetch(url)
+    .then(response => response.json())
+    .then(data => {{
+        console.log('시스템 상태:', data.status);
+        console.log('서비스:', data.services);
+    }})
+    .catch(error => {{
+        console.error('Error:', error);
+    }});'''
+    
+    else:
+        # 일반 케이스
+        params_str = "&".join([f"{k}={v}" for k, v in endpoint_info.get('example_params_current', endpoint_info['example_params']).items()])
+        js_code = f'''const stationId = 'DT_0001';
+const url = `{base_url}{endpoint_info['path']}?{params_str}`;
+
+fetch(url)
+    .then(response => response.json())
+    .then(data => {{
+        console.log(data);
+    }})
+    .catch(error => {{
+        console.error('Error:', error);
+    }});'''
+    
+    gr.Markdown("#### **JavaScript (`fetch` API)**")
+    gr.Markdown(f"```javascript\n{js_code}\n```")
+    
+    # 브라우저 직접 접속 - 복사 버튼 추가
+    gr.Markdown("#### **웹 브라우저**")
+    gr.Markdown("아래 주소를 복사하여 웹 브라우저 주소창에 붙여넣기만 해도 결과를 확인할 수 있습니다.")
+    
+    browser_params = ""
+    if endpoint_key != "health":
+        if endpoint_key == "compare":
+            browser_params = "?station_ids=DT_0001&station_ids=DT_0002"
+        else:
+            browser_params = "?" + "&".join([f"{k}={v}" for k, v in endpoint_info.get('example_params_current', {'station_id': 'DT_0001'}).items()])
+    
+    browser_url = f"{base_url}{endpoint_info['path']}{browser_params}"
+    
+    with gr.Row():
+        url_textbox = gr.Textbox(
+            value=browser_url, 
+            interactive=False, 
+            show_label=False,
+            scale=4
+        )
+        copy_btn = gr.Button("📋 복사", scale=1, size="sm")
+    
+    # 복사 버튼 클릭 이벤트
+    copy_btn.click(
+        fn=lambda x: x,  # 단순히 URL을 반환
+        inputs=[url_textbox],
+        outputs=[],
+        js=f"""(x) => {{
+            navigator.clipboard.writeText('{browser_url}');
+            alert('URL이 클립보드에 복사되었습니다!');
+            return x;
+        }}"""
+    )
+    
+    # 응답 형식
+    gr.Markdown("")
+    gr.Markdown("### 응답 형식 (Response Format)")
+    
+    # 성공 응답
+    gr.Markdown("#### **성공 (200 OK)**")
+    response_json = json.dumps(endpoint_info['response_example'], indent=2, ensure_ascii=False)
+    gr.Markdown(f"```json\n{response_json}\n```")
+    
+    # 실패 응답 (파라미터가 필요한 경우에만)
+    if any(p['required'] for p in endpoint_info['parameters']):
+        gr.Markdown("#### **실패 (422 Unprocessable Entity - 파라미터 누락 시)**")
+        error_response = '''{
+  "detail": [
+    {
+      "type": "missing",
+      "loc": [
+        "query",
+        "station_id"
+      ],
+      "msg": "Field required",
+      "input": null
+    }
+  ]
+}'''
+        gr.Markdown(f"```json\n{error_response}\n```")