Files

Roog (顾新培) 5921f71756 main:添加核心文件并初始化项目

新增内容：
- 创建基础项目结构。
- 添加 `.gitignore` 和 `.dockerignore` 文件。
- 编写 `pyproject.toml` 和依赖文件。
- 添加算法模块及示例算法。
- 实现核心功能模块（日志、错误处理、指标）。
- 添加开发和运行所需的相关脚本文件及文档。

2026-02-03 18:38:08 +08:00

1.9 KiB

Raw Blame History

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 模型包含完整的文档字符串和示例

1.9 KiB Raw Blame History Unescape Escape