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