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