{ "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": "创建异步任务，立即返回任务 ID，任务在后台执行", "operationId": "create_job_jobs_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/JobRequest" } } } }, "responses": { "202": { "description": "任务已创建", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreateResponse" } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "算法不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "服务不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/jobs/{job_id}": { "get": { "tags": [ "Algorithm" ], "summary": "查询任务状态", "description": "查询异步任务的执行状态和结果", "operationId": "get_job_status_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "任务不存在或已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "服务不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/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" } }, "JobCreateResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "任务唯一标识" }, "status": { "$ref": "#/components/schemas/JobStatus", "description": "任务状态" }, "message": { "type": "string", "title": "Message", "description": "状态消息" }, "created_at": { "type": "string", "title": "Created At", "description": "创建时间（ISO 8601）" } }, "type": "object", "required": [ "job_id", "status", "message", "created_at" ], "title": "JobCreateResponse", "description": "任务创建响应", "example": { "created_at": "2026-02-02T10:00:00Z", "job_id": "a1b2c3d4e5f6", "message": "任务已创建", "status": "pending" } }, "JobRequest": { "properties": { "algorithm": { "type": "string", "title": "Algorithm", "description": "算法名称" }, "params": { "additionalProperties": true, "type": "object", "title": "Params", "description": "算法参数" }, "webhook": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook", "description": "回调 URL" } }, "type": "object", "required": [ "algorithm", "params" ], "title": "JobRequest", "description": "异步任务请求", "example": { "algorithm": "PrimeChecker", "params": { "number": 17 }, "webhook": "https://example.com/callback" } }, "JobStatus": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ], "title": "JobStatus", "description": "任务状态枚举" }, "JobStatusResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "任务唯一标识" }, "status": { "$ref": "#/components/schemas/JobStatus", "description": "任务状态" }, "algorithm": { "type": "string", "title": "Algorithm", "description": "算法名称" }, "created_at": { "type": "string", "title": "Created At", "description": "创建时间（ISO 8601）" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Started At", "description": "开始执行时间（ISO 8601）" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At", "description": "完成时间（ISO 8601）" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result", "description": "执行结果（仅完成时返回）" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "错误信息（仅失败时返回）" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "元数据信息" } }, "type": "object", "required": [ "job_id", "status", "algorithm", "created_at" ], "title": "JobStatusResponse", "description": "任务状态查询响应", "example": { "algorithm": "PrimeChecker", "completed_at": "2026-02-02T10:00:02Z", "created_at": "2026-02-02T10:00:00Z", "job_id": "a1b2c3d4e5f6", "metadata": { "elapsed_time": 0.001 }, "result": { "is_prime": true, "number": 17 }, "started_at": "2026-02-02T10:00:01Z", "status": "completed" } }, "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" } } } }