{
  "openapi": "3.0.3",
  "info": {
    "title": "HWShare API",
    "description": "Public file sharing API for HWShare. Upload a file and receive a signed link that stays valid for 24 hours, after which the file is automatically deleted. No authentication required.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://share.hwctools.site",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Shares",
      "description": "Upload files and get 24-hour share links"
    },
    {
      "name": "Health",
      "description": "Service status"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": ["Health"],
        "summary": "Check service status",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "publicSharing", "maxUploadBytes"],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "publicSharing": {
                      "type": "boolean",
                      "description": "Whether anonymous public sharing is enabled",
                      "example": true
                    },
                    "maxUploadBytes": {
                      "type": "integer",
                      "description": "Maximum allowed upload size in bytes",
                      "example": 1073741824
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/shares": {
      "post": {
        "tags": ["Shares"],
        "summary": "Upload a file and create a 24-hour share link",
        "description": "Upload a single file (multipart/form-data). The response contains a pre-signed URL that anyone can use to download the file. The file and link expire after 24 hours and are then deleted automatically.",
        "operationId": "createShare",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The file to share"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Share created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["id", "name", "size", "url", "expiresIn", "deleteAt"],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Share identifier",
                      "example": "804ee34c-a344-4569-ac68-25f6743e84a8"
                    },
                    "name": {
                      "type": "string",
                      "description": "Original file name",
                      "example": "report.pdf"
                    },
                    "size": {
                      "type": "integer",
                      "description": "File size in bytes",
                      "example": 53982
                    },
                    "url": {
                      "type": "string",
                      "description": "Pre-signed download URL, valid for 24 hours",
                      "example": "https://hwshare.obs.sa-brazil-1.myhuaweicloud.com/__public/804ee34c-a344-4569-ac68-25f6743e84a8/report.pdf?X-Amz-Algorithm=..."
                    },
                    "expiresIn": {
                      "type": "integer",
                      "description": "Link lifetime in seconds",
                      "example": 86400
                    },
                    "deleteAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When the file is deleted",
                      "example": "2026-08-11T17:05:56.986Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No file provided",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Choose a file to share."
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "File too large",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Public sharing is not configured",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Public sharing is not configured yet."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}