{
  "openapi": "3.0.0",
  "info": {
    "title": "REST4i - File Operations Services",
    "description": "Enhanced file operations services supporting both IFS and SMB file operations with improved error handling and response formatting.",
    "version": "1.0.7-rest4i",
    "contact": {
      "name": "API Support",
      "url": "https://github.com/rest4i"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "/rest4i/api"
    }
  ],
  "tags": [
    {
      "name": "File Operations Services",
      "description": "Enhanced file operations services supporting both IFS and SMB file operations."
    }
  ],
  "paths": {
    "/v1/files/list": {
      "get": {
        "tags": ["File Operations Services"],
        "summary": "List directory contents",
        "description": "List files and directories at specified path using SMB/CIFS or IFS",
        "operationId": "listFiles",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "description": "Directory path to list",
            "schema": {
              "type": "string"
            },
            "example": "/home/user/documents"
          }
        ],
        "responses": {
          "200": {
            "description": "Directory listing successful",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "data": {
                    "path": "/home/user/documents",
                    "files": [
                      {
                        "name": "report.pdf",
                        "size": 102400,
                        "isDirectory": false
                      },
                      {
                        "name": "archive",
                        "size": 0,
                        "isDirectory": true
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/files/download": {
      "get": {
        "tags": ["File Operations Services"],
        "summary": "Download a file",
        "description": "Downloads a file from the specified SMB path.",
        "operationId": "downloadFile",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "description": "The SMB path to the file",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "description": "SMB domain",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "username",
            "in": "query",
            "description": "SMB username",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "description": "SMB password",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File downloaded successfully",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - path parameter required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "File not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/files/upload": {
      "post": {
        "tags": ["File Operations Services"],
        "summary": "Upload a file",
        "description": "Uploads a file to the specified SMB path.",
        "operationId": "uploadFile",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UploadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "File uploaded successfully",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "message": "File uploaded successfully",
                  "folder": "/upload/path",
                  "filename": "document.pdf"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/files/zip": {
      "get": {
        "tags": ["File Operations Services"],
        "summary": "Zip directory contents",
        "description": "Creates a ZIP archive of all files in the specified directory.",
        "operationId": "zipDirectory",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "description": "The SMB path to the directory",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "description": "SMB domain",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "username",
            "in": "query",
            "description": "SMB username",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "description": "SMB password",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Directory zipped successfully",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - path parameter required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Directory not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/files/exists": {
      "get": {
        "tags": ["File Operations Services"],
        "summary": "Check if file or directory exists",
        "description": "Checks whether a file or directory exists at the specified SMB path.",
        "operationId": "checkExists",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "description": "The SMB path to check",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "description": "SMB domain",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "username",
            "in": "query",
            "description": "SMB username",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "description": "SMB password",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Existence check completed",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "path": "/path/to/check",
                  "exists": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request - path parameter required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UploadRequest": {
        "type": "object",
        "properties": {
          "folder": {
            "type": "string",
            "description": "The target folder path for upload"
          },
          "filename": {
            "type": "string",
            "description": "The name of the file to upload"
          },
          "domain": {
            "type": "string",
            "description": "SMB domain"
          },
          "username": {
            "type": "string",
            "description": "SMB username"
          },
          "password": {
            "type": "string",
            "description": "SMB password"
          },
          "fileContent": {
            "type": "string",
            "format": "byte",
            "description": "Base64 encoded file content"
          }
        },
        "required": ["folder", "filename", "fileContent"]
      },
      "Problem": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "integer",
            "format": "int32"
          },
          "details": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerHttpAuthentication": {
        "type": "http",
        "description": "Bearer token authentication.",
        "scheme": "bearer",
        "bearerFormat": "Bearer [token]"
      },
      "basicHttpAuthentication": {
        "type": "http",
        "description": "Basic authentication.",
        "scheme": "basic"
      }
    }
  }
}