chore: restore open-api.yaml
This commit is contained in:
parent
6bcb68c552
commit
ab61878fbc
1 changed files with 245 additions and 0 deletions
245
open-api.yaml
Normal file
245
open-api.yaml
Normal file
|
|
@ -0,0 +1,245 @@
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: Proxmox Image Conversion Engine
|
||||||
|
description: |
|
||||||
|
Backend API that runs on the Proxmox host (`srv2`) to convert VMware images
|
||||||
|
(VMDK, VHD, etc.) to Proxmox‑compatible QCOW2, optionally shrink the disk,
|
||||||
|
and provision a VM with automatic boot‑type detection.
|
||||||
|
version: 1.1.0
|
||||||
|
contact:
|
||||||
|
name: Support
|
||||||
|
url: https://github.com/your-org/converter
|
||||||
|
|
||||||
|
servers:
|
||||||
|
- url: http://10.2.0.2:9000/api/v1
|
||||||
|
description: Internal Proxmox host (srv2)
|
||||||
|
|
||||||
|
paths:
|
||||||
|
/jobs:
|
||||||
|
post:
|
||||||
|
summary: Submit a new VM conversion and creation job
|
||||||
|
operationId: createJob
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/JobSubmissionRequest'
|
||||||
|
responses:
|
||||||
|
'202':
|
||||||
|
description: Job accepted and queued for processing
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/JobStatusResponse'
|
||||||
|
'400':
|
||||||
|
description: Invalid request or source file not found
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/jobs/{job_id}:
|
||||||
|
get:
|
||||||
|
summary: Get the current status of a conversion job
|
||||||
|
operationId: getJobStatus
|
||||||
|
parameters:
|
||||||
|
- name: job_id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
example: "job_10007_1784637888"
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Job status details
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/JobStatusResponse'
|
||||||
|
'404':
|
||||||
|
description: Job not found
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/jobs/{job_id}/cleanup:
|
||||||
|
post:
|
||||||
|
summary: Delete staging files or preserve them for reuse
|
||||||
|
operationId: cleanupJob
|
||||||
|
parameters:
|
||||||
|
- name: job_id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
example: "job_10007_1784637888"
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/CleanupRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Cleanup action performed
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
job_id:
|
||||||
|
type: string
|
||||||
|
action_taken:
|
||||||
|
type: string
|
||||||
|
enum: [purged, retained]
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
/health:
|
||||||
|
get:
|
||||||
|
summary: Health check endpoint
|
||||||
|
operationId: healthCheck
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Service is healthy
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
status:
|
||||||
|
type: string
|
||||||
|
example: ok
|
||||||
|
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
DiskSpec:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- disk_type
|
||||||
|
properties:
|
||||||
|
disk_type:
|
||||||
|
type: string
|
||||||
|
enum: [image_file, empty_disk]
|
||||||
|
description: |
|
||||||
|
`image_file` – convert an existing file from `source_filename`.
|
||||||
|
`empty_disk` – create a blank disk of the given `size_gb`.
|
||||||
|
source_filename:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: Path relative to `/mnt/converter/in` (required if `disk_type=image_file`)
|
||||||
|
example: "64bit/Debian 12.11.0 (64bit).vmdk"
|
||||||
|
size_gb:
|
||||||
|
type: integer
|
||||||
|
nullable: true
|
||||||
|
description: Size in GiB (required if `disk_type=empty_disk`)
|
||||||
|
example: 50
|
||||||
|
format:
|
||||||
|
type: string
|
||||||
|
enum: [qcow2, raw, vmdk]
|
||||||
|
default: qcow2
|
||||||
|
description: Source image format (for `image_file`)
|
||||||
|
|
||||||
|
JobSubmissionRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- vmid
|
||||||
|
- vm_name
|
||||||
|
- boot_disk
|
||||||
|
properties:
|
||||||
|
vmid:
|
||||||
|
type: integer
|
||||||
|
description: Proxmox VM ID (must be unique on host)
|
||||||
|
example: 10007
|
||||||
|
vm_name:
|
||||||
|
type: string
|
||||||
|
description: Display name for the VM
|
||||||
|
example: "debian-default-shrink"
|
||||||
|
boot_type:
|
||||||
|
type: string
|
||||||
|
enum: [uefi, legacy]
|
||||||
|
default: uefi
|
||||||
|
description: Boot firmware type (ignored if `auto_detect_boot=true`)
|
||||||
|
auto_detect_boot:
|
||||||
|
type: boolean
|
||||||
|
default: true
|
||||||
|
description: |
|
||||||
|
If `true`, automatically detects whether the disk is EFI‑bootable and
|
||||||
|
overrides `boot_type`. Falls back to `legacy` if detection fails.
|
||||||
|
cpu_cores:
|
||||||
|
type: integer
|
||||||
|
default: 4
|
||||||
|
minimum: 1
|
||||||
|
example: 2
|
||||||
|
ram_mb:
|
||||||
|
type: integer
|
||||||
|
default: 8192
|
||||||
|
minimum: 512
|
||||||
|
example: 4096
|
||||||
|
target_storage:
|
||||||
|
type: string
|
||||||
|
default: "local-lvm"
|
||||||
|
description: Proxmox storage pool for the VM disks
|
||||||
|
example: "local-lvm"
|
||||||
|
boot_disk:
|
||||||
|
$ref: '#/components/schemas/DiskSpec'
|
||||||
|
additional_disks:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/DiskSpec'
|
||||||
|
description: Additional data disks (converted or empty)
|
||||||
|
target_disk_size_gb:
|
||||||
|
type: integer
|
||||||
|
nullable: true
|
||||||
|
description: |
|
||||||
|
If provided, the boot disk (and only the boot disk) is resized to this
|
||||||
|
size (GiB). If omitted and the boot disk is larger than 30 GiB, it is
|
||||||
|
automatically shrunk to 30 GiB. Only shrinks when disk_type=image_file.
|
||||||
|
example: 40
|
||||||
|
|
||||||
|
JobStatusResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
job_id:
|
||||||
|
type: string
|
||||||
|
example: "job_10007_1784637888"
|
||||||
|
vmid:
|
||||||
|
type: integer
|
||||||
|
example: 10007
|
||||||
|
status:
|
||||||
|
type: string
|
||||||
|
enum: [queued, processing_conversion, importing_storage, completed, failed]
|
||||||
|
description: Current job phase
|
||||||
|
progress_percentage:
|
||||||
|
type: integer
|
||||||
|
minimum: 0
|
||||||
|
maximum: 100
|
||||||
|
example: 75
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
description: Human‑readable status message
|
||||||
|
example: "Creating VM and importing disks..."
|
||||||
|
error_details:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: If status is `failed`, contains the error reason
|
||||||
|
|
||||||
|
CleanupRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- delete_staging_files
|
||||||
|
properties:
|
||||||
|
delete_staging_files:
|
||||||
|
type: boolean
|
||||||
|
description: |
|
||||||
|
`true` – delete extracted source files and converted disk images.
|
||||||
|
`false` – keep files so another VM can be created from the same source.
|
||||||
|
|
||||||
|
ErrorResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
detail:
|
||||||
|
type: string
|
||||||
|
example: "Source file not found: 64bit/Debian 12.11.0 (64bit).vmdk"
|
||||||
Loading…
Reference in a new issue