main:添加核心文件并初始化项目
新增内容： - 创建基础项目结构。 - 添加 `.gitignore` 和 `.dockerignore` 文件。 - 编写 `pyproject.toml` 和依赖文件。 - 添加算法模块及示例算法。 - 实现核心功能模块（日志、错误处理、指标）。 - 添加开发和运行所需的相关脚本文件及文档。
This commit is contained in:
107
docs/swagger/README.md
Normal file
107
docs/swagger/README.md
Normal file
@@ -0,0 +1,107 @@
|
||||
# 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 模型包含完整的文档字符串和示例
|
||||
404
docs/swagger/openapi.json
Normal file
404
docs/swagger/openapi.json
Normal file
@@ -0,0 +1,404 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "FunctionalScaffold",
|
||||
"description": "算法工程化 Serverless 脚手架 - 提供标准化的算法服务接口",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"paths": {
|
||||
"/invoke": {
|
||||
"post": {
|
||||
"tags": [
|
||||
"Algorithm"
|
||||
],
|
||||
"summary": "同步调用算法",
|
||||
"description": "同步调用质数判断算法，立即返回结果",
|
||||
"operationId": "invoke_algorithm_invoke_post",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "x-request-id",
|
||||
"in": "header",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "X-Request-Id"
|
||||
}
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/InvokeRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "成功",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/InvokeResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "请求参数错误",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "服务器内部错误",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/HTTPValidationError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/healthz": {
|
||||
"get": {
|
||||
"tags": [
|
||||
"Algorithm"
|
||||
],
|
||||
"summary": "健康检查",
|
||||
"description": "检查服务是否存活",
|
||||
"operationId": "health_check_healthz_get",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/HealthResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/readyz": {
|
||||
"get": {
|
||||
"tags": [
|
||||
"Algorithm"
|
||||
],
|
||||
"summary": "就绪检查",
|
||||
"description": "检查服务是否就绪",
|
||||
"operationId": "readiness_check_readyz_get",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ReadinessResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/jobs": {
|
||||
"post": {
|
||||
"tags": [
|
||||
"Algorithm"
|
||||
],
|
||||
"summary": "异步任务接口（预留）",
|
||||
"description": "异步任务接口，当前版本未实现",
|
||||
"operationId": "create_job_jobs_post",
|
||||
"responses": {
|
||||
"501": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/metrics": {
|
||||
"get": {
|
||||
"tags": [
|
||||
"Monitoring"
|
||||
],
|
||||
"summary": "Prometheus 指标",
|
||||
"description": "导出 Prometheus 格式的监控指标",
|
||||
"operationId": "metrics_metrics_get",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"schemas": {
|
||||
"ErrorResponse": {
|
||||
"properties": {
|
||||
"error": {
|
||||
"type": "string",
|
||||
"title": "Error",
|
||||
"description": "错误代码"
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"title": "Message",
|
||||
"description": "错误消息"
|
||||
},
|
||||
"details": {
|
||||
"anyOf": [
|
||||
{
|
||||
"additionalProperties": true,
|
||||
"type": "object"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "Details",
|
||||
"description": "错误详情"
|
||||
},
|
||||
"request_id": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "Request Id",
|
||||
"description": "请求ID"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"error",
|
||||
"message"
|
||||
],
|
||||
"title": "ErrorResponse",
|
||||
"description": "错误响应",
|
||||
"example": {
|
||||
"details": {
|
||||
"field": "number",
|
||||
"value": "abc"
|
||||
},
|
||||
"error": "VALIDATION_ERROR",
|
||||
"message": "number must be an integer",
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
},
|
||||
"HTTPValidationError": {
|
||||
"properties": {
|
||||
"detail": {
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/ValidationError"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Detail"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"title": "HTTPValidationError"
|
||||
},
|
||||
"HealthResponse": {
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"title": "Status",
|
||||
"description": "健康状态"
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "number",
|
||||
"title": "Timestamp",
|
||||
"description": "时间戳"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"status",
|
||||
"timestamp"
|
||||
],
|
||||
"title": "HealthResponse",
|
||||
"description": "健康检查响应"
|
||||
},
|
||||
"InvokeRequest": {
|
||||
"properties": {
|
||||
"number": {
|
||||
"type": "integer",
|
||||
"title": "Number",
|
||||
"description": "待判断的整数"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"number"
|
||||
],
|
||||
"title": "InvokeRequest",
|
||||
"description": "同步调用请求",
|
||||
"example": {
|
||||
"number": 17
|
||||
}
|
||||
},
|
||||
"InvokeResponse": {
|
||||
"properties": {
|
||||
"request_id": {
|
||||
"type": "string",
|
||||
"title": "Request Id",
|
||||
"description": "请求唯一标识"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"title": "Status",
|
||||
"description": "处理状态"
|
||||
},
|
||||
"result": {
|
||||
"additionalProperties": true,
|
||||
"type": "object",
|
||||
"title": "Result",
|
||||
"description": "算法执行结果"
|
||||
},
|
||||
"metadata": {
|
||||
"additionalProperties": true,
|
||||
"type": "object",
|
||||
"title": "Metadata",
|
||||
"description": "元数据信息"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"request_id",
|
||||
"status",
|
||||
"result",
|
||||
"metadata"
|
||||
],
|
||||
"title": "InvokeResponse",
|
||||
"description": "同步调用响应",
|
||||
"example": {
|
||||
"metadata": {
|
||||
"algorithm": "PrimeChecker",
|
||||
"elapsed_time": 0.001,
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"request_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"result": {
|
||||
"algorithm": "trial_division",
|
||||
"factors": [],
|
||||
"is_prime": true,
|
||||
"number": 17
|
||||
},
|
||||
"status": "success"
|
||||
}
|
||||
},
|
||||
"ReadinessResponse": {
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"title": "Status",
|
||||
"description": "就绪状态"
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "number",
|
||||
"title": "Timestamp",
|
||||
"description": "时间戳"
|
||||
},
|
||||
"checks": {
|
||||
"anyOf": [
|
||||
{
|
||||
"additionalProperties": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "Checks",
|
||||
"description": "各项检查结果"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"status",
|
||||
"timestamp"
|
||||
],
|
||||
"title": "ReadinessResponse",
|
||||
"description": "就绪检查响应"
|
||||
},
|
||||
"ValidationError": {
|
||||
"properties": {
|
||||
"loc": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "integer"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Location"
|
||||
},
|
||||
"msg": {
|
||||
"type": "string",
|
||||
"title": "Message"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"title": "Error Type"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"loc",
|
||||
"msg",
|
||||
"type"
|
||||
],
|
||||
"title": "ValidationError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user