Roog (顾新培)
31af5e2286
新增内容： - 创建基础项目结构。 - 添加 `.gitignore` 和 `.dockerignore` 文件。 - 编写 `pyproject.toml` 和依赖文件。 - 添加算法模块及示例算法。 - 实现核心功能模块（日志、错误处理、指标）。 - 添加开发和运行所需的相关脚本文件及文档。
108 lines
1.9 KiB
Markdown
108 lines
1.9 KiB
Markdown
# Swagger 文档
|
||
|
||
本目录包含自动生成的 OpenAPI 规范文档。
|
||
|
||
## 生成文档
|
||
|
||
运行以下命令生成或更新 OpenAPI 规范：
|
||
|
||
```bash
|
||
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
|
||
|
||
```json
|
||
{
|
||
"number": 17
|
||
}
|
||
```
|
||
|
||
#### InvokeResponse
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"error": "ERROR_CODE",
|
||
"message": "Error description",
|
||
"details": {},
|
||
"request_id": "uuid"
|
||
}
|
||
```
|
||
|
||
## 更新文档
|
||
|
||
当修改 API 接口后，需要重新生成文档：
|
||
|
||
1. 修改代码（路由、模型等）
|
||
2. 运行 `python scripts/export_openapi.py`
|
||
3. 提交更新后的 `openapi.json`
|
||
|
||
## 注意事项
|
||
|
||
- `openapi.json` 是自动生成的，不要手动编辑
|
||
- 所有 API 变更都应该在代码中完成，然后重新生成文档
|
||
- 确保 Pydantic 模型包含完整的文档字符串和示例
|