Roog (顾新培)
5feb795d12
变更内容： - 移除冗余文档，包括 Grafana 指南、指标对比、修复总结、OpenAPI 规范等。 - 精简项目文档结构，优化 README 文件内容。 - 提升文档层次清晰度，集中核心指南。
736 lines
18 KiB
JSON
736 lines
18 KiB
JSON
{
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
} |