Roog (顾新培)
5921f71756
新增内容： - 创建基础项目结构。 - 添加 `.gitignore` 和 `.dockerignore` 文件。 - 编写 `pyproject.toml` 和依赖文件。 - 添加算法模块及示例算法。 - 实现核心功能模块（日志、错误处理、指标）。 - 添加开发和运行所需的相关脚本文件及文档。
Swagger 文档
本目录包含自动生成的 OpenAPI 规范文档。
生成文档
运行以下命令生成或更新 OpenAPI 规范：
python scripts/export_openapi.py
这将生成 openapi.json 文件，包含完整的 API 规范。
查看文档
在线查看
启动应用后，访问以下 URL：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
离线查看
使用 Swagger Editor 或其他 OpenAPI 工具打开 openapi.json 文件。
API 规范
端点列表
算法接口
-
POST /invoke- 同步调用算法- 请求体:
{"number": integer} - 响应: 算法执行结果
- 请求体:
-
POST /jobs- 异步任务接口（预留）- 当前返回 501 Not Implemented
健康检查
-
GET /healthz- 存活检查- 响应:
{"status": "healthy", "timestamp": float}
- 响应:
-
GET /readyz- 就绪检查- 响应:
{"status": "ready", "timestamp": float, "checks": {...}}
- 响应:
监控
GET /metrics- Prometheus 指标- 响应: Prometheus 文本格式
数据模型
InvokeRequest
{
"number": 17
}
InvokeResponse
{
"request_id": "uuid",
"status": "success",
"result": {
"number": 17,
"is_prime": true,
"factors": [],
"algorithm": "trial_division"
},
"metadata": {
"algorithm": "PrimeChecker",
"version": "1.0.0",
"elapsed_time": 0.001
}
}
ErrorResponse
{
"error": "ERROR_CODE",
"message": "Error description",
"details": {},
"request_id": "uuid"
}
更新文档
当修改 API 接口后，需要重新生成文档：
- 修改代码（路由、模型等）
- 运行
python scripts/export_openapi.py - 提交更新后的
openapi.json
注意事项
openapi.json是自动生成的，不要手动编辑- 所有 API 变更都应该在代码中完成，然后重新生成文档
- 确保 Pydantic 模型包含完整的文档字符串和示例