|
|
#!/usr/bin/env python3
|
|
|
# CodeDetect API文档生成器
|
|
|
|
|
|
import os
|
|
|
import sys
|
|
|
import re
|
|
|
import inspect
|
|
|
import json
|
|
|
from pathlib import Path
|
|
|
from typing import Dict, List, Any, Optional
|
|
|
from dataclasses import dataclass, asdict
|
|
|
|
|
|
@dataclass
|
|
|
class APIEndpoint:
|
|
|
"""API端点信息"""
|
|
|
method: str
|
|
|
path: str
|
|
|
description: str
|
|
|
parameters: List[Dict[str, Any]]
|
|
|
responses: Dict[str, Any]
|
|
|
auth_required: bool = False
|
|
|
|
|
|
@dataclass
|
|
|
class WebSocketEvent:
|
|
|
"""WebSocket事件信息"""
|
|
|
event_name: str
|
|
|
direction: str # 'send' or 'receive'
|
|
|
description: str
|
|
|
data_structure: Dict[str, Any]
|
|
|
|
|
|
class APIDocGenerator:
|
|
|
"""API文档生成器"""
|
|
|
|
|
|
def __init__(self, source_dir: str = "src"):
|
|
|
self.source_dir = Path(source_dir)
|
|
|
self.output_dir = Path("docs/api")
|
|
|
self.endpoints: List[APIEndpoint] = []
|
|
|
self.websocket_events: List[WebSocketEvent] = []
|
|
|
|
|
|
def generate_all_docs(self):
|
|
|
"""生成所有API文档"""
|
|
|
print("🚀 开始生成API文档...")
|
|
|
|
|
|
# 创建输出目录
|
|
|
self.output_dir.mkdir(parents=True, exist_ok=True)
|
|
|
|
|
|
# 扫描源代码
|
|
|
self._scan_api_endpoints()
|
|
|
self._scan_websocket_events()
|
|
|
|
|
|
# 生成文档
|
|
|
self._generate_rest_api_docs()
|
|
|
self._generate_websocket_docs()
|
|
|
self._generate_openapi_spec()
|
|
|
|
|
|
print("✅ API文档生成完成")
|
|
|
|
|
|
def _scan_api_endpoints(self):
|
|
|
"""扫描API端点"""
|
|
|
api_file = self.source_dir / "ui" / "api.py"
|
|
|
if not api_file.exists():
|
|
|
print(f"⚠️ API文件不存在: {api_file}")
|
|
|
return
|
|
|
|
|
|
print("📡 扫描REST API端点...")
|
|
|
|
|
|
# 简单的端点检测逻辑
|
|
|
content = api_file.read_text()
|
|
|
|
|
|
# 查找路由定义
|
|
|
route_pattern = r'@(\w+)\.route\([\'"]([^\'"]+)[\'"](?:,\s*methods=\[([^\]]+)\])?\)'
|
|
|
matches = re.findall(route_pattern, content)
|
|
|
|
|
|
for decorator, path, methods in matches:
|
|
|
if methods:
|
|
|
method_list = [m.strip().strip('\'"') for m in methods.split(',')]
|
|
|
else:
|
|
|
method_list = ['GET']
|
|
|
|
|
|
for method in method_list:
|
|
|
endpoint = APIEndpoint(
|
|
|
method=method,
|
|
|
path=path,
|
|
|
description=f"{method} {path}",
|
|
|
parameters=[],
|
|
|
responses={"200": {"description": "Success"}}
|
|
|
)
|
|
|
self.endpoints.append(endpoint)
|
|
|
|
|
|
print(f" 发现 {len(self.endpoints)} 个API端点")
|
|
|
|
|
|
def _scan_websocket_events(self):
|
|
|
"""扫描WebSocket事件"""
|
|
|
socketio_file = self.source_dir / "ui" / "socketio_handlers.py"
|
|
|
if not socketio_file.exists():
|
|
|
print(f"⚠️ WebSocket文件不存在: {socketio_file}")
|
|
|
return
|
|
|
|
|
|
print("🔌 扫描WebSocket事件...")
|
|
|
|
|
|
content = socketio_file.read_text()
|
|
|
|
|
|
# 查找事件处理器
|
|
|
event_pattern = r'@socketio\.on\([\'"]([^\'"]+)[\'"]\)'
|
|
|
matches = re.findall(event_pattern, content)
|
|
|
|
|
|
for event_name in matches:
|
|
|
event = WebSocketEvent(
|
|
|
event_name=event_name,
|
|
|
direction="receive",
|
|
|
description=f"WebSocket事件: {event_name}",
|
|
|
data_structure={}
|
|
|
)
|
|
|
self.websocket_events.append(event)
|
|
|
|
|
|
print(f" 发现 {len(self.websocket_events)} 个WebSocket事件")
|
|
|
|
|
|
def _generate_rest_api_docs(self):
|
|
|
"""生成REST API文档"""
|
|
|
doc_content = """# CodeDetect REST API 参考
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
CodeDetect提供RESTful API用于代码验证和突变生成。
|
|
|
|
|
|
## 认证
|
|
|
|
|
|
大多数API端点需要认证。使用Bearer Token格式：
|
|
|
|
|
|
```
|
|
|
Authorization: Bearer <your-api-key>
|
|
|
```
|
|
|
|
|
|
## 基础URL
|
|
|
|
|
|
```
|
|
|
http://localhost:5000/api/v1
|
|
|
```
|
|
|
|
|
|
"""
|
|
|
|
|
|
# 按路径分组端点
|
|
|
endpoints_by_path = {}
|
|
|
for endpoint in self.endpoints:
|
|
|
if endpoint.path not in endpoints_by_path:
|
|
|
endpoints_by_path[endpoint.path] = []
|
|
|
endpoints_by_path[endpoint.path].append(endpoint)
|
|
|
|
|
|
# 生成端点文档
|
|
|
for path, path_endpoints in endpoints_by_path.items():
|
|
|
doc_content += f"\n## {path}\n\n"
|
|
|
|
|
|
for endpoint in path_endpoints:
|
|
|
doc_content += f"### {endpoint.method} {path}\n\n"
|
|
|
doc_content += f"{endpoint.description}\n\n"
|
|
|
|
|
|
if endpoint.parameters:
|
|
|
doc_content += "#### 请求参数\n\n"
|
|
|
for param in endpoint.parameters:
|
|
|
doc_content += f"- **{param['name']}** ({param['type']}): {param['description']}\n"
|
|
|
doc_content += "\n"
|
|
|
|
|
|
doc_content += "#### 响应\n\n"
|
|
|
for status, response in endpoint.responses.items():
|
|
|
doc_content += f"**{status}**: {response['description']}\n\n"
|
|
|
|
|
|
doc_content += "---\n\n"
|
|
|
|
|
|
# 写入文件
|
|
|
(self.output_dir / "rest-api.md").write_text(doc_content)
|
|
|
|
|
|
def _generate_websocket_docs(self):
|
|
|
"""生成WebSocket文档"""
|
|
|
doc_content = """# CodeDetect WebSocket API 参考
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
CodeDetect使用WebSocket提供实时更新和进度通知。
|
|
|
|
|
|
## 连接
|
|
|
|
|
|
```javascript
|
|
|
const socket = io('http://localhost:5000');
|
|
|
```
|
|
|
|
|
|
## 事件
|
|
|
|
|
|
"""
|
|
|
|
|
|
# 生成事件文档
|
|
|
for event in self.websocket_events:
|
|
|
doc_content += f"### {event.event_name}\n\n"
|
|
|
doc_content += f"**方向**: {event.direction}\n\n"
|
|
|
doc_content += f"{event.description}\n\n"
|
|
|
|
|
|
if event.data_structure:
|
|
|
doc_content += "#### 数据结构\n\n"
|
|
|
doc_content += "```json\n"
|
|
|
doc_content += json.dumps(event.data_structure, indent=2, ensure_ascii=False)
|
|
|
doc_content += "\n```\n\n"
|
|
|
|
|
|
doc_content += "---\n\n"
|
|
|
|
|
|
# 写入文件
|
|
|
(self.output_dir / "websocket-api.md").write_text(doc_content)
|
|
|
|
|
|
def _generate_openapi_spec(self):
|
|
|
"""生成OpenAPI规范"""
|
|
|
spec = {
|
|
|
"openapi": "3.0.0",
|
|
|
"info": {
|
|
|
"title": "CodeDetect API",
|
|
|
"version": "1.0.0",
|
|
|
"description": "CodeDetect代码验证和突变生成API"
|
|
|
},
|
|
|
"servers": [
|
|
|
{
|
|
|
"url": "http://localhost:5000/api/v1",
|
|
|
"description": "开发服务器"
|
|
|
}
|
|
|
],
|
|
|
"paths": {},
|
|
|
"components": {
|
|
|
"securitySchemes": {
|
|
|
"BearerAuth": {
|
|
|
"type": "http",
|
|
|
"scheme": "bearer",
|
|
|
"bearerFormat": "JWT"
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
|
|
|
# 添加路径
|
|
|
for endpoint in self.endpoints:
|
|
|
path = endpoint.path
|
|
|
method = endpoint.method.lower()
|
|
|
|
|
|
if path not in spec["paths"]:
|
|
|
spec["paths"][path] = {}
|
|
|
|
|
|
spec["paths"][path][method] = {
|
|
|
"summary": endpoint.description,
|
|
|
"responses": endpoint.responses
|
|
|
}
|
|
|
|
|
|
if endpoint.auth_required:
|
|
|
spec["paths"][path][method]["security"] = [{"BearerAuth": []}]
|
|
|
|
|
|
# 写入文件
|
|
|
(self.output_dir / "openapi.json").write_text(
|
|
|
json.dumps(spec, indent=2, ensure_ascii=False)
|
|
|
)
|
|
|
|
|
|
def main():
|
|
|
"""主函数"""
|
|
|
generator = APIDocGenerator()
|
|
|
generator.generate_all_docs()
|
|
|
|
|
|
if __name__ == "__main__":
|
|
|
main() |
