{
  "components": {
    "schemas": {
      "CPUResource": {
        "properties": {
          "cores": {
            "type": "integer"
          },
          "freq_mhz": {
            "type": "integer"
          },
          "load_avg": {
            "items": {
              "type": "number"
            },
            "type": "array"
          },
          "max_freq_mhz": {
            "type": "integer"
          },
          "max_temp_c": {
            "type": "number"
          },
          "model": {
            "type": "string"
          },
          "per_core_percent": {
            "items": {
              "type": "number"
            },
            "type": "array"
          },
          "temp_c": {
            "description": "最高温度传感器读数(°C)",
            "type": "number"
          },
          "temp_zones": {
            "items": {
              "$ref": "#/components/schemas/TempZone"
            },
            "type": "array"
          },
          "usage_percent": {
            "description": "CPU 总体使用率(%)",
            "type": "number"
          }
        },
        "type": "object"
      },
      "DiskResource": {
        "properties": {
          "free_gb": {
            "type": "number"
          },
          "path": {
            "type": "string"
          },
          "total_gb": {
            "type": "number"
          },
          "usage_percent": {
            "type": "number"
          },
          "used_gb": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "Error": {
        "properties": {
          "error": {
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "ok": {
            "example": false,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "HostStatus": {
        "properties": {
          "arch": {
            "type": "string"
          },
          "boot_time": {
            "type": "string"
          },
          "cpu_cores": {
            "type": "integer"
          },
          "cpu_model": {
            "type": "string"
          },
          "cpu_temp_c": {
            "type": "number"
          },
          "cups_running": {
            "type": "boolean"
          },
          "disk_free_gb": {
            "type": "number"
          },
          "disk_total_gb": {
            "type": "number"
          },
          "disk_usage_pct": {
            "type": "number"
          },
          "disk_used_gb": {
            "type": "number"
          },
          "go_version": {
            "type": "string"
          },
          "goroutines": {
            "type": "integer"
          },
          "hostname": {
            "type": "string"
          },
          "ip_addresses": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "kernel": {
            "type": "string"
          },
          "load_avg": {
            "items": {
              "type": "number"
            },
            "type": "array"
          },
          "mem_available_mb": {
            "type": "integer"
          },
          "mem_total_mb": {
            "type": "integer"
          },
          "mem_usage_pct": {
            "type": "number"
          },
          "mem_used_mb": {
            "type": "integer"
          },
          "online": {
            "type": "boolean"
          },
          "os": {
            "type": "string"
          },
          "service_pid": {
            "type": "integer"
          },
          "service_uptime_seconds": {
            "type": "number"
          },
          "time": {
            "type": "string"
          },
          "uptime_seconds": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "Job": {
        "properties": {
          "completed_at": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "id": {
            "type": "integer"
          },
          "impressions_completed": {
            "type": "integer"
          },
          "media_sheets_completed": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "printer_uri": {
            "type": "string"
          },
          "processing_at": {
            "type": "string"
          },
          "size_kb": {
            "type": "integer"
          },
          "state": {
            "enum": [
              "pending",
              "pending-held",
              "processing",
              "processing-stopped",
              "canceled",
              "aborted",
              "completed",
              "unknown"
            ],
            "type": "string"
          },
          "state_code": {
            "type": "integer"
          },
          "state_reasons": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "user": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "MemoryResource": {
        "properties": {
          "available_mb": {
            "type": "integer"
          },
          "buffers_cache_mb": {
            "type": "integer"
          },
          "free_mb": {
            "type": "integer"
          },
          "swap_free_mb": {
            "type": "integer"
          },
          "swap_total_mb": {
            "type": "integer"
          },
          "swap_usage_percent": {
            "type": "number"
          },
          "swap_used_mb": {
            "type": "integer"
          },
          "total_mb": {
            "type": "integer"
          },
          "usage_percent": {
            "type": "number"
          },
          "used_mb": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PrintJSONRequest": {
        "properties": {
          "color_mode": {
            "type": "string"
          },
          "content_base64": {
            "description": "文档内容的 base64",
            "format": "byte",
            "type": "string"
          },
          "copies": {
            "type": "integer"
          },
          "document_format": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "job_name": {
            "type": "string"
          },
          "media": {
            "type": "string"
          },
          "orientation": {
            "type": "string"
          },
          "page_ranges": {
            "type": "string"
          },
          "printer": {
            "type": "string"
          },
          "resolution": {
            "type": "string"
          },
          "sides": {
            "type": "string"
          },
          "text": {
            "description": "纯文本内容",
            "type": "string"
          }
        },
        "type": "object"
      },
      "Printer": {
        "properties": {
          "defaults": {
            "type": "object"
          },
          "device_uri": {
            "type": "string"
          },
          "is_accepting_jobs": {
            "type": "boolean"
          },
          "make_and_model": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "printer_uri": {
            "type": "string"
          },
          "queued_job_count": {
            "type": "integer"
          },
          "state": {
            "enum": [
              "idle",
              "processing",
              "stopped",
              "unknown"
            ],
            "type": "string"
          },
          "state_change_time": {
            "type": "string"
          },
          "state_code": {
            "type": "integer"
          },
          "state_message": {
            "type": "string"
          },
          "state_reasons": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "supplies": {
            "items": {
              "$ref": "#/components/schemas/Supply"
            },
            "type": "array"
          },
          "up_time_seconds": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ResourceStatus": {
        "properties": {
          "cpu": {
            "$ref": "#/components/schemas/CPUResource"
          },
          "disk": {
            "$ref": "#/components/schemas/DiskResource"
          },
          "hostname": {
            "type": "string"
          },
          "memory": {
            "$ref": "#/components/schemas/MemoryResource"
          },
          "time": {
            "type": "string"
          },
          "uptime_seconds": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "Supply": {
        "properties": {
          "color": {
            "type": "string"
          },
          "high": {
            "type": "integer"
          },
          "level": {
            "type": "integer"
          },
          "low": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "TempZone": {
        "properties": {
          "name": {
            "type": "string"
          },
          "temp_c": {
            "type": "number"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "ApiKeyHeader": {
        "in": "header",
        "name": "X-API-Key",
        "type": "apiKey"
      },
      "Bearer": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "armbian 主机上的打印 API：主机状态、打印机状态查询、文档打印、任务管理。通过本机 CUPS 驱动局域网打印机。",
    "title": "printer_service 打印服务 API",
    "version": "1.0.0"
  },
  "openapi": "3.0.3",
  "paths": {
    "/api/host": {
      "get": {
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HostStatus"
                }
              }
            },
            "description": "主机状态"
          }
        },
        "summary": "armbian 主机在线状态",
        "tags": [
          "system"
        ]
      }
    },
    "/api/host/resources": {
      "get": {
        "description": "返回 CPU 总体与每核使用率、CPU 温度与各温度传感器、CPU 频率、负载、内存与交换、磁盘占用。",
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceStatus"
                }
              }
            },
            "description": "资源使用情况"
          }
        },
        "summary": "主机资源使用情况（CPU/内存/温度/磁盘）",
        "tags": [
          "system"
        ]
      }
    },
    "/api/jobs": {
      "get": {
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "任务范围",
            "in": "query",
            "name": "which",
            "schema": {
              "default": "active",
              "enum": [
                "active",
                "completed",
                "all"
              ],
              "type": "string"
            }
          },
          {
            "description": "返回条数上限",
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 50,
              "type": "integer"
            }
          },
          {
            "description": "打印机名称，缺省为默认打印机",
            "in": "query",
            "name": "printer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "jobs": {
                      "items": {
                        "$ref": "#/components/schemas/Job"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "任务列表"
          }
        },
        "summary": "任务列表",
        "tags": [
          "job"
        ]
      }
    },
    "/api/jobs/{id}": {
      "get": {
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            },
            "description": "任务状态"
          }
        },
        "summary": "单任务状态",
        "tags": [
          "job"
        ]
      }
    },
    "/api/jobs/{id}/cancel": {
      "post": {
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "打印机名称",
            "in": "query",
            "name": "printer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "已取消"
          }
        },
        "summary": "取消任务",
        "tags": [
          "job"
        ]
      }
    },
    "/api/print": {
      "post": {
        "description": "支持 multipart/form-data（file 字段）、application/json（content_base64 或 text）、以及原始字节流（Content-Type 为文档 MIME，如 application/pdf）。",
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "打印机名称，缺省为 CUPS 默认打印机",
            "in": "query",
            "name": "printer",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "任务名",
            "in": "query",
            "name": "job_name",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "份数",
            "in": "query",
            "name": "copies",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "纸张，如 iso_a4_210x297mm",
            "in": "query",
            "name": "media",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "color 或 monochrome",
            "in": "query",
            "name": "color_mode",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "one-sided / two-sided-long-edge / two-sided-short-edge",
            "in": "query",
            "name": "sides",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "portrait / landscape",
            "in": "query",
            "name": "orientation",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "页码范围，如 1-3,5",
            "in": "query",
            "name": "page_ranges",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "分辨率，如 300x300",
            "in": "query",
            "name": "resolution",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "文档 MIME，缺省按文件名识别",
            "in": "query",
            "name": "document_format",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrintJSONRequest"
              }
            },
            "application/pdf": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            },
            "image/jpeg": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            },
            "image/png": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            },
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "color_mode": {
                    "type": "string"
                  },
                  "copies": {
                    "type": "integer"
                  },
                  "file": {
                    "format": "binary",
                    "type": "string"
                  },
                  "job_name": {
                    "type": "string"
                  },
                  "media": {
                    "type": "string"
                  },
                  "orientation": {
                    "type": "string"
                  },
                  "page_ranges": {
                    "type": "string"
                  },
                  "printer": {
                    "type": "string"
                  },
                  "resolution": {
                    "type": "string"
                  },
                  "sides": {
                    "type": "string"
                  }
                },
                "required": [
                  "file"
                ],
                "type": "object"
              }
            },
            "text/plain": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "accepted": {
                      "type": "boolean"
                    },
                    "job": {
                      "$ref": "#/components/schemas/Job"
                    },
                    "job_id": {
                      "type": "integer"
                    },
                    "printer": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "已受理打印"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "参数错误"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "密钥错误"
          },
          "413": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "内容过大"
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "CUPS 交互失败"
          }
        },
        "summary": "提交打印任务",
        "tags": [
          "print"
        ]
      }
    },
    "/api/printers": {
      "get": {
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "active_job_count": {
                      "type": "integer"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "default_printer": {
                      "type": "string"
                    },
                    "printers": {
                      "items": {
                        "$ref": "#/components/schemas/Printer"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "打印机列表"
          }
        },
        "summary": "打印机列表",
        "tags": [
          "printer"
        ]
      }
    },
    "/api/printers/{name}": {
      "get": {
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "打印机名称",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "打印机详情"
          }
        },
        "summary": "单台打印机详情",
        "tags": [
          "printer"
        ]
      }
    },
    "/api/printers/{name}/raw": {
      "get": {
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "原始属性"
          }
        },
        "summary": "打印机原始 IPP 属性",
        "tags": [
          "printer"
        ]
      }
    },
    "/api/printers/{name}/test-page": {
      "post": {
        "description": "生成一张包含主机状态的测试页并提交打印，用于验证 armbian → CUPS → 打印机 链路。",
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "打印机名称",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "份数",
            "in": "query",
            "name": "copies",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "任务名",
            "in": "query",
            "name": "job_name",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "已受理"
          }
        },
        "summary": "打印测试页",
        "tags": [
          "print"
        ]
      }
    },
    "/api/whoami": {
      "get": {
        "parameters": [
          {
            "description": "访问密钥（也可用 Authorization: Bearer <KEY>）",
            "in": "header",
            "name": "X-API-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "密钥有效"
          }
        },
        "summary": "校验密钥",
        "tags": [
          "system"
        ]
      }
    },
    "/health": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "服务正常"
          }
        },
        "summary": "服务与主机存活探针（免密钥）",
        "tags": [
          "system"
        ]
      }
    }
  },
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "Bearer": []
    }
  ],
  "servers": [
    {
      "description": "公网地址",
      "url": "https://19563.ai-x-service.top"
    },
    {
      "description": "armbian 本机",
      "url": "http://127.0.0.1:19563"
    }
  ],
  "tags": [
    {
      "description": "主机与服务状态",
      "name": "system"
    },
    {
      "description": "打印机",
      "name": "printer"
    },
    {
      "description": "打印",
      "name": "print"
    },
    {
      "description": "任务",
      "name": "job"
    }
  ]
}