dailz/hpc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(openapi): update spec to match code — add Tasks, fix schemas, remove submit endpoint

Browse Source 
- Add Tasks tag, /tasks paths, and Task schemas (CreateTaskRequest, TaskResponse, TaskListResponse)

- Fix SubmitJobRequest.work_dir, InitUploadRequest mime_type/chunk_size, UploadSessionResponse.created_at

- Fix FolderResponse: add file_count/subfolder_count, remove updated_at

- Fix response wrapping for File/Upload/Folder endpoints to use ApiResponseSuccess

- Remove /applications/{id}/submit path and ApplicationSubmitRequest schema

- Update Applications tag description

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
dailz
2026-04-16 15:15:31 +08:00
parent 52a34e2cb0
commit 80f2bd32d9
1 changed files with 376 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

456
hpc_server_openapi.json
View File

@@ -22,7 +22,7 @@
}, },
{ {
"name": "Applications", "name": "Applications",
"description": "Application definition CRUD and job submission" "description": "Application definition CRUD"
}, },
{ {
"name": "File Uploads", "name": "File Uploads",
@@ -35,6 +35,10 @@
{ {
"name": "Folders", "name": "Folders",
"description": "Folder CRUD with materialized path hierarchy" "description": "Folder CRUD with materialized path hierarchy"
},
{
"name": "Tasks",
"description": "Task creation, listing, and lifecycle management"
} }
], ],
"paths": { "paths": {
@@ -1002,79 +1006,6 @@
} }
} }
}, },
"/applications/{id}/submit": {
"post": {
"tags": ["Applications"],
"summary": "Submit a job from an application",
"description": "Submits a Slurm job using the application's script template and provided parameter values.",
"operationId": "submitApplication",
"parameters": [
{ "$ref": "#/components/parameters/ApplicationId" }
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationSubmitRequest"
}
}
}
},
"responses": {
"201": {
"description": "Job submitted successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/JobResponse"
}
}
}
]
}
}
}
},
"400": {
"description": "Invalid request body or missing required parameter values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
},
"404": {
"description": "Application not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
},
"502": {
"description": "Slurm backend error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
}
}
}
},
"/diag": { "/diag": {
"get": { "get": {
"tags": ["Cluster"], "tags": ["Cluster"],
@@ -1138,20 +1069,40 @@
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/UploadSessionResponse" "$ref": "#/components/schemas/UploadSessionResponse"
} }
} }
} }
]
}
}
}
}, },
"200": { "200": {
"description": "Dedup hit - file already exists, returns existing file", "description": "Dedup hit - file already exists, returns existing file",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/FileResponse" "$ref": "#/components/schemas/FileResponse"
} }
} }
} }
]
}
}
}
}, },
"400": { "400": {
"description": "Invalid request", "description": "Invalid request",
@@ -1262,10 +1213,20 @@
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/FileResponse" "$ref": "#/components/schemas/FileResponse"
} }
} }
} }
]
}
}
}
}, },
"400": { "400": {
"description": "Invalid request or missing chunks", "description": "Invalid request or missing chunks",
@@ -1317,10 +1278,20 @@
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/UploadSessionResponse" "$ref": "#/components/schemas/UploadSessionResponse"
} }
} }
} }
]
}
}
}
}, },
"404": { "404": {
"description": "Upload session not found", "description": "Upload session not found",
@@ -1418,10 +1389,20 @@
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/FileListResponse" "$ref": "#/components/schemas/FileListResponse"
} }
} }
} }
]
}
}
}
}, },
"500": { "500": {
"description": "Internal server error", "description": "Internal server error",
@@ -1452,10 +1433,20 @@
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/FileResponse" "$ref": "#/components/schemas/FileResponse"
} }
} }
} }
]
}
}
}
}, },
"404": { "404": {
"description": "File not found", "description": "File not found",
@@ -1602,10 +1593,20 @@
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/FolderResponse" "$ref": "#/components/schemas/FolderResponse"
} }
} }
} }
]
}
}
}
}, },
"400": { "400": {
"description": "Invalid request", "description": "Invalid request",
@@ -1648,6 +1649,12 @@
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/FolderResponse" "$ref": "#/components/schemas/FolderResponse"
@@ -1655,6 +1662,10 @@
} }
} }
} }
]
}
}
}
}, },
"500": { "500": {
"description": "Internal server error", "description": "Internal server error",
@@ -1685,10 +1696,20 @@
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/FolderResponse" "$ref": "#/components/schemas/FolderResponse"
} }
} }
} }
]
}
}
}
}, },
"404": { "404": {
"description": "Folder not found", "description": "Folder not found",
@@ -1758,6 +1779,144 @@
} }
} }
} }
},
"/tasks": {
"post": {
"tags": ["Tasks"],
"summary": "Create a new task",
"description": "Creates an HPC task from an application definition with parameter values.",
"operationId": "createTask",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTaskRequest"
}
}
}
},
"responses": {
"201": {
"description": "Task created successfully",
"content": {
"application/json": {
"schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Created task ID"
}
}
}
}
}
]
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
}
}
},
"get": {
"tags": ["Tasks"],
"summary": "List tasks",
"description": "Retrieves a paginated list of tasks with optional status filter.",
"operationId": "listTasks",
"parameters": [
{
"name": "page",
"in": "query",
"description": "Page number (starts from 1)",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "page_size",
"in": "query",
"description": "Number of items per page",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"default": 20
}
},
{
"name": "status",
"in": "query",
"description": "Filter by task status",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Paginated list of tasks",
"content": {
"application/json": {
"schema": {
"allOf": [
{ "$ref": "#/components/schemas/ApiResponseSuccess" },
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/TaskListResponse"
}
}
}
]
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
}
}
}
} }
}, },
"components": { "components": {
@@ -1907,6 +2066,10 @@
"type": "string" "type": "string"
}, },
"description": "Environment variables" "description": "Environment variables"
},
"work_dir": {
"type": "string",
"description": "Job working directory"
} }
} }
}, },
@@ -2448,19 +2611,6 @@
} }
} }
}, },
"ApplicationSubmitRequest": {
"type": "object",
"required": ["values"],
"properties": {
"values": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Parameter name to value mapping"
}
}
},
"ApplicationListResponse": { "ApplicationListResponse": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -2487,7 +2637,7 @@
}, },
"InitUploadRequest": { "InitUploadRequest": {
"type": "object", "type": "object",
"required": ["file_name", "file_size", "sha256", "chunk_size"], "required": ["file_name", "file_size", "sha256"],
"properties": { "properties": {
"file_name": { "file_name": {
"type": "string", "type": "string",
@@ -2512,6 +2662,10 @@
"format": "int64", "format": "int64",
"description": "Target folder ID (null for root)", "description": "Target folder ID (null for root)",
"nullable": true "nullable": true
},
"mime_type": {
"type": "string",
"description": "MIME type of the file"
} }
} }
}, },
@@ -2561,6 +2715,11 @@
"type": "string", "type": "string",
"format": "date-time", "format": "date-time",
"description": "Session expiration time" "description": "Session expiration time"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Session creation time"
} }
} }
}, },
@@ -2651,11 +2810,17 @@
"type": "string", "type": "string",
"description": "Materialized path (e.g. /data/reports/)" "description": "Materialized path (e.g. /data/reports/)"
}, },
"created_at": { "file_count": {
"type": "string", "type": "integer",
"format": "date-time" "format": "int64",
"description": "Number of files in this folder"
}, },
"updated_at": { "subfolder_count": {
"type": "integer",
"format": "int64",
"description": "Number of sub-folders in this folder"
},
"created_at": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time"
} }
@@ -2676,6 +2841,113 @@
"nullable": true "nullable": true
} }
} }
},
"CreateTaskRequest": {
"type": "object",
"required": ["app_id"],
"properties": {
"app_id": {
"type": "integer",
"format": "int64",
"description": "Application ID to create task from"
},
"task_name": {
"type": "string",
"description": "Task name"
},
"values": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Parameter name to value mapping"
},
"file_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "Input file IDs"
}
}
},
"TaskResponse": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Task ID"
},
"task_name": {
"type": "string",
"description": "Task name"
},
"app_id": {
"type": "integer",
"format": "int64",
"description": "Application ID"
},
"app_name": {
"type": "string",
"description": "Application name"
},
"status": {
"type": "string",
"description": "Task status",
"enum": ["submitted", "preparing", "downloading", "ready", "queued", "running", "completed", "failed"]
},
"current_step": {
"type": "string",
"description": "Current processing step"
},
"retry_count": {
"type": "integer",
"description": "Number of retries"
},
"slurm_job_id": {
"type": "integer",
"format": "int32",
"description": "Slurm job ID",
"nullable": true
},
"work_dir": {
"type": "string",
"description": "Working directory"
},
"error_message": {
"type": "string",
"description": "Error message if failed"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp"
}
}
},
"TaskListResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskResponse"
},
"description": "List of tasks"
},
"total": {
"type": "integer",
"format": "int64",
"description": "Total number of matching tasks"
}
}
} }
} }
} }