FunctionalScaffold/docs/swagger/openapi.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": "异步任务接口，当前版本未实现",
        "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"
      }
    }
  }
}