#!/usr/bin/env python3 """ CodeDetect API文档生成工具 自动从源代码生成API文档，支持: - REST API端点文档 - WebSocket事件文档 - 内部模块API文档 - 配置参数文档 - 示例代码生成 """ import ast import os import sys import json import re import inspect import importlib.util from pathlib import Path from typing import Dict, List, Any, Optional, Tuple from dataclasses import dataclass, asdict from datetime import datetime import yaml import markdown @dataclass class APIEndpoint: """API端点信息""" method: str path: str description: str parameters: List[Dict[str, Any]] responses: Dict[str, Dict[str, Any]] examples: List[Dict[str, Any]] authentication: bool rate_limit: Optional[str] = None @dataclass class WebSocketEvent: """WebSocket事件信息""" event: str direction: str # 'client_to_server' or 'server_to_client' description: str payload: Dict[str, Any] examples: List[Dict[str, Any]] @dataclass class ModuleAPI: """模块API信息""" module_name: str description: str classes: List[Dict[str, Any]] functions: List[Dict[str, Any]] constants: List[Dict[str, Any]] examples: List[str] @dataclass class ConfigParameter: """配置参数信息""" name: str type: str default_value: Any description: str required: bool options: Optional[List[str]] = None class APIDocGenerator: """API文档生成器""" def __init__(self, project_root: str, output_dir: str): self.project_root = Path(project_root) self.output_dir = Path(output_dir) self.output_dir.mkdir(parents=True, exist_ok=True) # 初始化数据结构 self.api_endpoints: List[APIEndpoint] = [] self.websocket_events: List[WebSocketEvent] = [] self.module_apis: List[ModuleAPI] = [] self.config_parameters: List[ConfigParameter] = [] # 忽略的文件和目录 self.ignore_patterns = [ '__pycache__', '.git', '.pytest_cache', 'venv', 'env', 'node_modules', 'build', 'dist', '*.pyc' ] def generate_all_docs(self): """生成所有API文档""" print("🚀 开始生成API文档...") # 扫描源代码 self._scan_source_code() # 解析Flask路由 self._parse_flask_routes() # 解析WebSocket事件 self._parse_websocket_events() # 解析配置文件 self._parse_config_files() # 生成各种文档 self._generate_rest_api_docs() self._generate_websocket_docs() self._generate_module_docs() self._generate_config_docs() self._generate_examples() self._generate_index() print("✅ API文档生成完成!") def _scan_source_code(self): """扫描源代码文件""" print("📂 扫描源代码...") src_dir = self.project_root / "src" if not src_dir.exists(): print(f"⚠️ 源代码目录不存在: {src_dir}") return for py_file in src_dir.rglob("*.py"): if any(pattern in str(py_file) for pattern in self.ignore_patterns): continue try: self._parse_python_file(py_file) except Exception as e: print(f"⚠️ 解析文件失败 {py_file}: {e}") def _parse_python_file(self, file_path: Path): """解析Python文件""" try: with open(file_path, 'r', encoding='utf-8') as f: content = f.read() tree = ast.parse(content) module_name = self._get_module_name(file_path) module_api = ModuleAPI( module_name=module_name, description="", classes=[], functions=[], constants=[], examples=[] ) for node in ast.walk(tree): if isinstance(node, ast.ClassDef): self._parse_class(node, module_api) elif isinstance(node, ast.FunctionDef): self._parse_function(node, module_api) elif isinstance(node, ast.Assign): self._parse_assign(node, module_api) if module_api.classes or module_api.functions: self.module_apis.append(module_api) except Exception as e: print(f"⚠️ 解析Python文件失败 {file_path}: {e}") def _parse_class(self, node: ast.ClassDef, module_api: ModuleAPI): """解析类定义""" class_info = { "name": node.name, "docstring": ast.get_docstring(node) or "", "methods": [], "properties": [] } for item in node.body: if isinstance(item, ast.FunctionDef): method_info = { "name": item.name, "docstring": ast.get_docstring(item) or "", "parameters": self._get_function_parameters(item), "returns": self._get_function_returns(item), "decorators": [self._get_decorator_name(d) for d in item.decorator_list] } class_info["methods"].append(method_info) module_api.classes.append(class_info) def _parse_function(self, node: ast.FunctionDef, module_api: ModuleAPI): """解析函数定义""" if not hasattr(node, 'parent_class'): # 不在类中的函数 function_info = { "name": node.name, "docstring": ast.get_docstring(node) or "", "parameters": self._get_function_parameters(node), "returns": self._get_function_returns(node), "decorators": [self._get_decorator_name(d) for d in node.decorator_list] } module_api.functions.append(function_info) def _parse_assign(self, node: ast.Assign, module_api: ModuleAPI): """解析赋值语句""" for target in node.targets: if isinstance(target, ast.Name): if target.id.isupper(): # 常量 constant_info = { "name": target.id, "value": self._get_constant_value(node.value), "docstring": "" # 可以从注释中提取 } module_api.constants.append(constant_info) def _get_module_name(self, file_path: Path) -> str: """获取模块名""" relative_path = file_path.relative_to(self.project_root / "src") module_path = str(relative_path.with_suffix('')).replace(os.sep, '.') return module_path def _get_function_parameters(self, node: ast.FunctionDef) -> List[Dict[str, Any]]: """获取函数参数""" parameters = [] for arg in node.args.args: param_info = { "name": arg.arg, "type": "", "default": None, "docstring": "" } # 尝试从类型注解获取类型 if arg.annotation: param_info["type"] = self._get_type_string(arg.annotation) parameters.append(param_info) return parameters def _get_function_returns(self, node: ast.FunctionDef) -> str: """获取函数返回类型""" if node.returns: return self._get_type_string(node.returns) return "" def _get_type_string(self, node: ast.AST) -> str: """获取类型字符串""" if isinstance(node, ast.Name): return node.id elif isinstance(node, ast.Attribute): return f"{node.value.id}.{node.attr}" elif isinstance(node, ast.Subscript): value = self._get_type_string(node.value) slice_value = self._get_type_string(node.slice) return f"{value}[{slice_value}]" else: return "" def _get_decorator_name(self, node: ast.AST) -> str: """获取装饰器名称""" if isinstance(node, ast.Name): return node.id elif isinstance(node, ast.Attribute): return f"{node.value.id}.{node.attr}" return "" def _get_constant_value(self, node: ast.AST) -> Any: """获取常量值""" if isinstance(node, ast.Constant): return node.value elif isinstance(node, ast.List): return [self._get_constant_value(elt) for elt in node.elts] elif isinstance(node, ast.Dict): return { self._get_constant_value(k): self._get_constant_value(v) for k, v in zip(node.keys, node.values) } else: return str(node) def _parse_flask_routes(self): """解析Flask路由""" print("🌐 解析Flask路由...") api_files = [ self.project_root / "src" / "ui" / "api.py", self.project_root / "src" / "api" / "routes.py" ] for file_path in api_files: if not file_path.exists(): continue try: self._parse_flask_file(file_path) except Exception as e: print(f"⚠️ 解析Flask文件失败 {file_path}: {e}") def _parse_flask_file(self, file_path: Path): """解析Flask文件""" with open(file_path, 'r', encoding='utf-8') as f: content = f.read() # 使用正则表达式提取路由信息 route_pattern = r'@(\w+)\.route\([\'"]([^\'\"]+)[\'"](?:,\s*methods=\[([^\]]+)\])?\)' for match in re.finditer(route_pattern, content): blueprint = match.group(1) path = match.group(2) methods = match.group(3) if methods: method_list = [m.strip().strip('\'"') for m in methods.split(',')] else: method_list = ['GET'] for method in method_list: # 提取函数文档字符串 func_start = match.end() func_pattern = r'def\s+(\w+)\s*\([^)]*\):\s*"""([^"]*)"""' func_match = re.search(func_pattern, content[func_start:]) description = "" if func_match: description = func_match.group(2).strip() endpoint = APIEndpoint( method=method, path=path, description=description, parameters=[], responses={}, examples=[], authentication=True ) self.api_endpoints.append(endpoint) def _parse_websocket_events(self): """解析WebSocket事件""" print("🔌 解析WebSocket事件...") # 从现有文档和代码中提取WebSocket事件 events = [ WebSocketEvent( event="file_upload", direction="client_to_server", description="客户端上传文件", payload={"file_id": "string", "filename": "string", "size": "number"}, examples=[{ "event": "file_upload", "data": {"file_id": "file_123", "filename": "test.c", "size": 1024} }] ), WebSocketEvent( event="verification_progress", direction="server_to_client", description="验证进度更新", payload={"job_id": "string", "progress": "number", "status": "string"}, examples=[{ "event": "verification_progress", "data": {"job_id": "job_456", "progress": 75, "status": "running"} }] ), WebSocketEvent( event="verification_result", direction="server_to_client", description="验证结果通知", payload={"job_id": "string", "result": "object", "success": "boolean"}, examples=[{ "event": "verification_result", "data": {"job_id": "job_456", "result": {...}, "success": true} }] ) ] self.websocket_events.extend(events) def _parse_config_files(self): """解析配置文件""" print("⚙️ 解析配置文件...") config_files = [ self.project_root / "config" / "default.yaml", self.project_root / "config" / "development.yaml", self.project_root / "config" / "production.yaml" ] for config_file in config_files: if not config_file.exists(): continue try: with open(config_file, 'r', encoding='utf-8') as f: config_data = yaml.safe_load(f) self._parse_config_data(config_data, config_file.name) except Exception as e: print(f"⚠️ 解析配置文件失败 {config_file}: {e}") def _parse_config_data(self, config_data: Dict[str, Any], filename: str): """解析配置数据""" def traverse_config(data: Dict[str, Any], prefix: str = ""): for key, value in data.items(): full_key = f"{prefix}.{key}" if prefix else key if isinstance(value, dict): traverse_config(value, full_key) else: param = ConfigParameter( name=full_key, type=type(value).__name__, default_value=value, description=f"配置参数 {full_key} 来自 {filename}", required=False ) self.config_parameters.append(param) if isinstance(config_data, dict): traverse_config(config_data) def _generate_rest_api_docs(self): """生成REST API文档""" print("📄 生成REST API文档...") md_content = """# REST API 文档 ## 概述 CodeDetect提供RESTful API用于代码验证、规范生成和结果查询。 ## 基础信息 - **基础URL**: `http://localhost:8080/api` - **认证方式**: Bearer Token - **内容类型**: `application/json` - **字符编码**: UTF-8 ## 通用响应格式 所有API响应都遵循以下格式： ```json { "success": true, "data": {}, "message": "操作成功", "timestamp": "2024-01-01T00:00:00Z" } ``` 错误响应格式： ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "错误描述", "details": {} }, "timestamp": "2024-01-01T00:00:00Z" } ``` ## API端点列表 """ # 按方法分组 endpoints_by_method = {} for endpoint in self.api_endpoints: if endpoint.method not in endpoints_by_method: endpoints_by_method[endpoint.method] = [] endpoints_by_method[endpoint.method].append(endpoint) for method in ['GET', 'POST', 'PUT', 'DELETE']: if method in endpoints_by_method: md_content += f"### {method} 端点\n\n" for endpoint in endpoints_by_method[method]: md_content += f"#### {method} {endpoint.path}\n\n" if endpoint.description: md_content += f"**描述**: {endpoint.description}\n\n" md_content += f"**认证**: {'是' if endpoint.authentication else '否'}\n\n" if endpoint.parameters: md_content += "**参数**:\n\n" for param in endpoint.parameters: md_content += f"- `{param['name']}` ({param['type']}): {param.get('description', '')}\n" md_content += "\n" if endpoint.examples: md_content += "**示例**:\n\n" for example in endpoint.examples: md_content += "```json\n" md_content += json.dumps(example, indent=2, ensure_ascii=False) md_content += "\n```\n\n" md_content += "---\n\n" # 保存文档 with open(self.output_dir / "rest-api.md", 'w', encoding='utf-8') as f: f.write(md_content) def _generate_websocket_docs(self): """生成WebSocket文档""" print("🔌 生成WebSocket文档...") md_content = """# WebSocket API 文档 ## 概述 CodeDetect使用WebSocket提供实时通信，用于进度更新、结果通知等功能。 ## 连接信息 - **WebSocket URL**: `ws://localhost:8080/ws` - **协议**: WebSocket - **消息格式**: JSON ## 消息格式 所有WebSocket消息都遵循以下格式： ```json { "event": "事件名称", "data": {}, "timestamp": "2024-01-01T00:00:00Z" } ``` ## 事件列表 """ # 按方向分组 events_by_direction = {} for event in self.websocket_events: if event.direction not in events_by_direction: events_by_direction[event.direction] = [] events_by_direction[event.direction].append(event) for direction in ['client_to_server', 'server_to_client']: direction_name = "客户端 → 服务器" if direction == 'client_to_server' else "服务器 → 客户端" md_content += f"### {direction_name}\n\n" if direction in events_by_direction: for event in events_by_direction[direction]: md_content += f"#### {event.event}\n\n" md_content += f"**描述**: {event.description}\n\n" if event.payload: md_content += "**数据结构**:\n\n" md_content += "```json\n" md_content += json.dumps(event.payload, indent=2, ensure_ascii=False) md_content += "\n```\n\n" if event.examples: md_content += "**示例**:\n\n" for example in event.examples: md_content += "```json\n" md_content += json.dumps(example, indent=2, ensure_ascii=False) md_content += "\n```\n\n" md_content += "---\n\n" # 保存文档 with open(self.output_dir / "websocket-api.md", 'w', encoding='utf-8') as f: f.write(md_content) def _generate_module_docs(self): """生成模块文档""" print("📦 生成模块文档...") md_content = """# 内部模块 API 文档 ## 概述 本文档描述了CodeDetect内部模块的API，供开发者和贡献者使用。 ## 模块列表 """ for module in self.module_apis: md_content += f"### {module.module_name}\n\n" if module.description: md_content += f"**描述**: {module.description}\n\n" if module.classes: md_content += "#### 类\n\n" for class_info in module.classes: md_content += f"##### {class_info['name']}\n\n" if class_info['docstring']: md_content += f"**说明**: {class_info['docstring']}\n\n" if class_info['methods']: md_content += "**方法**:\n\n" for method in class_info['methods']: md_content += f"- `{method['name']}({', '.join(p['name'] for p in method['parameters'])})`\n" if method['docstring']: md_content += f" - {method['docstring']}\n" md_content += "\n" if module.functions: md_content += "#### 函数\n\n" for function in module.functions: md_content += f"##### {function['name']}()\n\n" if function['docstring']: md_content += f"**说明**: {function['docstring']}\n\n" if function['parameters']: md_content += "**参数**:\n\n" for param in function['parameters']: md_content += f"- `{param['name']}`: {param['type']}\n" md_content += "\n" if function['returns']: md_content += f"**返回值**: {function['returns']}\n\n" md_content += "---\n\n" # 保存文档 with open(self.output_dir / "internal-api.md", 'w', encoding='utf-8') as f: f.write(md_content) def _generate_config_docs(self): """生成配置文档""" print("⚙️ 生成配置文档...") md_content = """# 配置参数文档 ## 概述 本文档描述了CodeDetect的所有配置参数及其说明。 ## 配置文件位置 - 默认配置: `config/default.yaml` - 开发环境: `config/development.yaml` - 生产环境: `config/production.yaml` ## 配置参数列表 """ # 按类型分组 params_by_type = {} for param in self.config_parameters: if param.type not in params_by_type: params_by_type[param.type] = [] params_by_type[param.type].append(param) for param_type in sorted(params_by_type.keys()): md_content += f"### {param_type} 类型\n\n" for param in params_by_type[param_type]: md_content += f"#### {param.name}\n\n" md_content += f"**默认值**: `{param.default_value}`\n\n" md_content += f"**是否必需**: {'是' if param.required else '否'}\n\n" md_content += f"**说明**: {param.description}\n\n" if param.options: md_content += "**可选值**:\n\n" for option in param.options: md_content += f"- `{option}`\n" md_content += "\n" md_content += "---\n\n" # 保存文档 with open(self.output_dir / "configuration.md", 'w', encoding='utf-8') as f: f.write(md_content) def _generate_examples(self): """生成示例代码""" print("💻 生成示例代码...") # 创建示例目录 examples_dir = self.output_dir / "examples" examples_dir.mkdir(exist_ok=True) # 生成各种示例 examples = { "basic_usage.py": """#!/usr/bin/env python3 """ \"\"\" CodeDetect基础使用示例 演示如何使用CodeDetect进行基本的代码验证。 \"\"\" import asyncio import json from pathlib import Path # 导入CodeDetect模块 from src.verify.cbmc_runner import CBMCRunner from src.mutate.engine import MutationEngine from src.parse.code_parser import CodeParser async def basic_verification_example(): \"\"\"基础验证示例\"\"\" print("=== 基础验证示例 ===") # 示例代码 code = \"\"\" int add(int a, int b) { return a + b; } \"\"\" # 解析代码 parser = CodeParser() with open("temp_example.c", "w") as f: f.write(code) try: # 解析函数信息 parse_result = parser.parse_file("temp_example.c") print(f"找到 {len(parse_result.functions)} 个函数") for func in parse_result.functions: print(f"- {func.name}: {func.return_type}") print(f" 参数: {[p.name + ': ' + p.type for p in func.parameters]}") # 生成验证规范 specification = \"\"\" void add_test() { int a = __CPROVER_nondet_int(); int b = __CPROVER_nondet_int(); // 约束输入范围 __CPROVER_assume(a >= -1000 && a <= 1000); __CPROVER_assume(b >= -1000 && b <= 1000); int result = add(a, b); // 验证结果 __CPROVER_assert(result == a + b, "addition_correct"); } \"\"\" # 运行验证 runner = CBMCRunner() result = await runner.run_verification( function_metadata={"name": "add"}, source_file="temp_example.c", specification=specification ) print(f"验证结果: {result.status}") print(f"执行时间: {result.execution_time}s") finally: # 清理临时文件 if Path("temp_example.c").exists(): Path("temp_example.c").unlink() async def mutation_example(): \"\"\"突变生成示例\"\"\" print("\\n=== 突变生成示例 ===") # 基础规范 base_spec = \"\"\" void add_test() { int a = __CPROVER_nondet_int(); int b = __CPROVER_nondet_int(); int result = add(a, b); __CPROVER_assert(result == a + b, "addition_correct"); } \"\"\" # 函数元数据 function_metadata = [{ "name": "add", "return_type": "int", "parameters": [ {"name": "a", "type": "int"}, {"name": "b", "type": "int"} ], "complexity_score": 0.3 }] # 生成突变 engine = MutationEngine() mutations = engine.generate_mutations( base_spec, function_metadata, max_mutations=3 ) print(f"生成了 {len(mutations)} 个突变:") for i, mutation in enumerate(mutations): print(f"\\n突变 {i+1}:") print(f"类型: {mutation.mutation_type}") print(f"置信度: {mutation.confidence:.2f}") print(f"规范:\\n{mutation.specification}") async def main(): \"\"\"主函数\"\"\" try: await basic_verification_example() await mutation_example() except Exception as e: print(f"示例执行失败: {e}") if __name__ == "__main__": asyncio.run(main()) """, "freertos_example.py": """#!/usr/bin/env python3 """ \"\"\" FreeRTOS验证示例 演示如何使用CodeDetect验证FreeRTOS代码。 \"\"\" import asyncio from pathlib import Path from src.verify.cbmc_runner import CBMCRunner from src.mutate.engine import MutationEngine async def freertos_task_verification(): \"\"\"FreeRTOS任务验证示例\"\"\" print("=== FreeRTOS任务验证示例 ===") # FreeRTOS任务代码 freertos_code = \"\"\" #include "FreeRTOS.h" #include "task.h" typedef struct { int task_id; int counter; int max_count; BaseType_t should_stop; } TaskParameters_t; void vCounterTask(void *pvParameters) { TaskParameters_t *params = (TaskParameters_t *)pvParameters; // 参数验证 configASSERT(params != NULL); configASSERT(params->task_id > 0); configASSERT(params->max_count > 0); while (params->should_stop == pdFALSE) { if (params->counter < params->max_count) { params->counter++; } vTaskDelay(pdMS_TO_TICKS(100)); } vTaskDelete(NULL); } \"\"\" # 保存代码到文件 with open("freertos_task_example.c", "w") as f: f.write(freertos_code) try: # FreeRTOS验证规范 specification = \"\"\" #include "FreeRTOS.h" #include "task.h" typedef struct { int task_id; int counter; int max_count; BaseType_t should_stop; } TaskParameters_t; void test_task_creation() { TaskParameters_t params; TaskHandle_t task_handle; // 初始化参数 params.task_id = 1; params.counter = 0; params.max_count = 10; params.should_stop = pdFALSE; // 测试任务创建 BaseType_t result = xTaskCreate( vCounterTask, "CounterTask", configMINIMAL_STACK_SIZE, ¶ms, 1, &task_handle ); __CPROVER_assert(result == pdPASS, "task_creation_success"); __CPROVER_assert(task_handle != NULL, "task_handle_not_null"); } void test_parameter_validation() { TaskParameters_t *params = (TaskParameters_t *)__CPROVER_allocate(sizeof(TaskParameters_t)); // 测试NULL指针检查 vCounterTask(params); // 测试有效参数 params->task_id = __CPROVER_nondet_int(); params->max_count = __CPROVER_nondet_int(); __CPROVER_assume(params->task_id > 0); __CPROVER_assume(params->max_count > 0); vCounterTask(params); } \"\"\" # 运行验证 runner = CBMCRunner() result = await runner.run_verification( function_metadata={"name": "vCounterTask"}, source_file="freertos_task_example.c", specification=specification ) print(f"FreeRTOS验证结果: {result.status}") print(f"执行时间: {result.execution_time}s") finally: # 清理临时文件 if Path("freertos_task_example.c").exists(): Path("freertos_task_example.c").unlink() async def main(): \"\"\"主函数\"\"\" try: await freertos_task_verification() except Exception as e: print(f"FreeRTOS示例执行失败: {e}") if __name__ == "__main__": asyncio.run(main()) """ } for filename, content in examples.items(): with open(examples_dir / filename, 'w', encoding='utf-8') as f: f.write(content) def _generate_index(self): """生成索引文档""" print("📑 生成索引文档...") md_content = f"""# CodeDetect API 文档 > 生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')} ## 概述 CodeDetect是一个基于LLM和CBMC的C代码形式化验证系统。本文档提供了完整的API参考，包括REST API、WebSocket事件、内部模块API和配置参数。 ## 文档结构 ### 1. [REST API](rest-api.md) - API端点列表 - 请求/响应格式 - 认证和权限 - 示例代码 ### 2. [WebSocket API](websocket-api.md) - 实时通信事件 - 消息格式 - 连接管理 - 示例代码 ### 3. [内部模块 API](internal-api.md) - 核心模块接口 - 类和函数说明 - 使用示例 - 扩展开发 ### 4. [配置参数](configuration.md) - 系统配置 - 环境变量 - 参数说明 - 最佳实践 ### 5. [示例代码](examples/) - 基础使用示例 - FreeRTOS验证示例 - 自定义扩展示例 ## 快速开始 ### 安装依赖 ```bash pip install -r requirements.txt ``` ### 基础使用 ```python from src.verify.cbmc_runner import CBMCRunner from src.mutate.engine import MutationEngine # 创建验证器 runner = CBMCRunner() engine = MutationEngine() # 运行验证 result = await runner.run_verification( function_metadata={"name": "test_function"}, source_file="test.c", specification="void test() { }" ) ``` ## 贡献指南 如果您发现文档问题或想要贡献，请： 1. 查看源代码中的注释和文档字符串 2. 运行文档生成脚本 3. 提交Pull Request ## 技术支持 - 📧 邮箱: support@codedetect.com - 📖 文档: [在线文档](https://docs.codedetect.com) - 🐛 问题报告: [GitHub Issues](https://github.com/codedetect/issues) --- *本文档由自动生成工具创建* """ # 保存索引文档 with open(self.output_dir / "README.md", 'w', encoding='utf-8') as f: f.write(md_content) def main(): """主函数""" import argparse parser = argparse.ArgumentParser(description='CodeDetect API文档生成工具') parser.add_argument('--project-root', type=str, default='.', help='项目根目录 (默认: .)') parser.add_argument('--output-dir', type=str, default='docs/api', help='输出目录 (默认: docs/api)') parser.add_argument('--verbose', action='store_true', help='详细输出') args = parser.parse_args() # 生成文档 generator = APIDocGenerator(args.project_root, args.output_dir) generator.generate_all_docs() print(f"\n📚 文档已生成到: {args.output_dir}") print("📖 开始阅读: docs/api/README.md") if __name__ == "__main__": main()