vstash/templates/openapi/schemas.yaml

# S3 API Schemas

S3Error:
  type: object
  xml:
    name: Error
  properties:
    Code:
      type: string
      example: "NoSuchBucket"
    Message:
      type: string
      example: "The specified bucket does not exist"
    Resource:
      type: string
      example: "/mybucket"
    RequestId:
      type: string
      example: "4442587FB7D0A2F9"

ListAllMyBucketsResult:
  type: object
  xml:
    name: ListAllMyBucketsResult
    namespace: http://s3.amazonaws.com/doc/2006-03-01/
  properties:
    Buckets:
      type: object
      properties:
        Bucket:
          type: array
          items:
            $ref: '#/Bucket'

Bucket:
  type: object
  properties:
    Name:
      type: string
      example: "my-bucket"
    CreationDate:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00.000Z"

ListBucketResult:
  type: object
  xml:
    name: ListBucketResult
    namespace: http://s3.amazonaws.com/doc/2006-03-01/
  properties:
    Name:
      type: string
      example: "my-bucket"
    Prefix:
      type: string
      example: "photos/"
    Marker:
      type: string
      example: "photos/2023/"
    MaxKeys:
      type: integer
      example: 1000
    IsTruncated:
      type: boolean
      example: false
    Contents:
      type: array
      items:
        $ref: '#/ObjectSummary'

ObjectSummary:
  type: object
  properties:
    Key:
      type: string
      example: "photos/2023/vacation.jpg"
    LastModified:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00.000Z"
    ETag:
      type: string
      example: "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
    Size:
      type: integer
      example: 1024000
    StorageClass:
      type: string
      example: "STANDARD"

InitiateMultipartUploadResult:
  type: object
  xml:
    name: InitiateMultipartUploadResult
    namespace: http://s3.amazonaws.com/doc/2006-03-01/
  properties:
    Bucket:
      type: string
      example: "my-bucket"
    Key:
      type: string
      example: "large-file.zip"
    UploadId:
      type: string
      example: "upload_12345_abcdef"

CompleteMultipartUpload:
  type: object
  xml:
    name: CompleteMultipartUpload
  properties:
    Part:
      type: array
      items:
        type: object
        properties:
          PartNumber:
            type: integer
            example: 1
          ETag:
            type: string
            example: "\"9bb58f26192e4ba00f01e2e7b136bbd8\""

CompleteMultipartUploadResult:
  type: object
  xml:
    name: CompleteMultipartUploadResult
    namespace: http://s3.amazonaws.com/doc/2006-03-01/
  properties:
    Location:
      type: string
      example: "/my-bucket/large-file.zip"
    Bucket:
      type: string
      example: "my-bucket"
    Key:
      type: string
      example: "large-file.zip"
    ETag:
      type: string
      example: "\"9bb58f26192e4ba00f01e2e7b136bbd8-5\""

ListPartsResult:
  type: object
  xml:
    name: ListPartsResult
    namespace: http://s3.amazonaws.com/doc/2006-03-01/
  properties:
    Bucket:
      type: string
      example: "my-bucket"
    Key:
      type: string
      example: "large-file.zip"
    UploadId:
      type: string
      example: "upload_12345_abcdef"
    StorageClass:
      type: string
      example: "STANDARD"
    PartNumberMarker:
      type: integer
      example: 0
    NextPartNumberMarker:
      type: integer
      example: 5
    MaxParts:
      type: integer
      example: 1000
    IsTruncated:
      type: boolean
      example: false
    Part:
      type: array
      items:
        $ref: '#/Part'

Part:
  type: object
  properties:
    PartNumber:
      type: integer
      example: 1
    LastModified:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00.000Z"
    ETag:
      type: string
      example: "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
    Size:
      type: integer
      example: 5242880

ListMultipartUploadsResult:
  type: object
  xml:
    name: ListMultipartUploadsResult
    namespace: http://s3.amazonaws.com/doc/2006-03-01/
  properties:
    Bucket:
      type: string
      example: "my-bucket"
    KeyMarker:
      type: string
      example: ""
    UploadIdMarker:
      type: string
      example: ""
    NextKeyMarker:
      type: string
      example: ""
    NextUploadIdMarker:
      type: string
      example: ""
    MaxUploads:
      type: integer
      example: 1000
    IsTruncated:
      type: boolean
      example: false
    Upload:
      type: array

MultipartUpload:
  type: object
  properties:
    Key:
      type: string
      example: "large-file.zip"
    UploadId:
      type: string
      example: "upload_12345_abcdef"
    Initiated:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00.000Z"
    StorageClass:
      type: string
      example: "STANDARD"

# Management API Schemas

ApiError:
  type: object
  properties:
    error:
      type: string
      example: "Resource not found"
    code:
      type: string
      example: "NOT_FOUND"
    message:
      type: string
      example: "The requested resource could not be found"

ApiResponse:
  type: object
  properties:
    message:
      type: string
      example: "Operation completed successfully"

SystemStats:
  type: object
  properties:
    credentials:
      type: integer
      example: 5
      description: Total number of access credentials
    buckets:
      type: integer
      example: 12
      description: Total number of buckets
    objects:
      type: integer
      example: 1250
      description: Total number of objects
    total_storage:
      type: integer
      example: 1073741824
      description: Total storage used in bytes
    total_storage_human:
      type: string
      example: "1.0 GB"
      description: Human-readable storage size
    active_multipart_uploads:
      type: integer
      example: 3
      description: Number of active multipart uploads
    active_presigned_urls:
      type: integer
      example: 15
      description: Number of active presigned URLs

Credential:
  type: object
  properties:
    id:
      type: integer
      example: 1
    access_key:
      type: string
      example: "AKIAIOSFODNN7EXAMPLE"
    secret_key:
      type: string
      example: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
      description: Only returned when creating credential
    user_name:
      type: string
      example: "john-doe"
      nullable: true
    is_active:
      type: boolean
      example: true
    created_at:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00Z"

CredentialSummary:
  type: object
  properties:
    id:
      type: integer
      example: 1
    access_key:
      type: string
      example: "AKIAIOSFODNN7EXAMPLE"
    user_name:
      type: string
      example: "john-doe"
      nullable: true
    is_active:
      type: boolean
      example: true
    created_at:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00Z"
    bucket_count:
      type: integer
      example: 3

CredentialDetail:
  allOf:
    - $ref: '#/CredentialSummary'
    - type: object
      properties:
        buckets:
          type: array
          items:
            $ref: '#/BucketSummary'

CredentialsList:
  type: object
  properties:
    credentials:
      type: array
      items:
        $ref: '#/CredentialSummary'

CreateCredentialRequest:
  type: object
  properties:
    user_name:
      type: string
      example: "john-doe"
      description: Optional user name
    access_key:
      type: string
      example: "AKIAIOSFODNN7EXAMPLE"
      description: Optional custom access key (auto-generated if not provided)
    secret_key:
      type: string
      example: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
      description: Optional custom secret key (auto-generated if not provided)

UpdateCredentialRequest:
  type: object
  properties:
    user_name:
      type: string
      example: "john-doe"
    is_active:
      type: boolean
      example: true

BucketSummary:
  type: object
  properties:
    name:
      type: string
      example: "my-bucket"
    region:
      type: string
      example: "us-east-1"
    owner:
      type: string
      example: "john-doe"
    created_at:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00Z"
    object_count:
      type: integer
      example: 150
    total_size:
      type: integer
      example: 1073741824
    total_size_human:
      type: string
      example: "1.0 GB"

BucketDetail:
  allOf:
    - $ref: '#/BucketSummary'
    - type: object
      properties:
        objects:
          type: array
          items:
            $ref: '#/ObjectInfo'

BucketsList:
  type: object
  properties:
    buckets:
      type: array
      items:
        $ref: '#/BucketSummary'

CreateBucketRequest:
  type: object
  required:
    - name
    - owner_id
  properties:
    name:
      type: string
      example: "my-new-bucket"
      pattern: '^[a-z0-9\-\.]+$'
    owner_id:
      type: integer
      example: 1
    region:
      type: string
      example: "us-east-1"
      default: "us-east-1"

ObjectInfo:
  type: object
  properties:
    key:
      type: string
      example: "photos/vacation.jpg"
    size:
      type: integer
      example: 1024000
    size_human:
      type: string
      example: "1.0 MB"
    content_type:
      type: string
      example: "image/jpeg"
    etag:
      type: string
      example: "9bb58f26192e4ba00f01e2e7b136bbd8"
    is_multipart:
      type: boolean
      example: false
    created_at:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00Z"

ObjectDetail:
  allOf:
    - $ref: '#/ObjectInfo'
    - type: object
      properties:
        part_count:
          type: integer
          example: 0
        metadata:
          type: object
          additionalProperties:
            type: string
          example:
            user-id: "12345"
            category: "photos"
        storage_path:
          type: string
          example: "my-bucket/objects/ab/cd/abcdef123456..."
        updated_at:
          type: string
          format: date-time
          example: "2023-01-15T10:30:00Z"

ObjectsList:
  type: object
  properties:
    objects:
      type: array
      items:
        $ref: '#/ObjectInfo'

DeleteObjectsRequest:
  type: object
  required:
    - keys
  properties:
    keys:
      type: array
      items:
        type: string
      example: ["file1.txt", "file2.txt", "folder/file3.txt"]

DeleteObjectsResponse:
  type: object
  properties:
    deleted:
      type: array
      items:
        type: string
      example: ["file1.txt", "file2.txt"]

MultipartUploadInfo:
  type: object
  properties:
    upload_id:
      type: string
      example: "upload_12345_abcdef"
    object_key:
      type: string
      example: "large-file.zip"
    initiated_by:
      type: string
      example: "john-doe"
    content_type:
      type: string
      example: "application/zip"
    initiated_at:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00Z"
    part_count:
      type: integer
      example: 5
    total_size:
      type: integer
      example: 26214400
    total_size_human:
      type: string
      example: "25.0 MB"

MultipartUploadsList:
  type: object
  properties:
    uploads:
      type: array
      items:
        $ref: '#/MultipartUploadInfo'

PresignedUrlInfo:
  type: object
  properties:
    bucket_name:
      type: string
      example: "my-bucket"
    object_key:
      type: string
      example: "file.txt"
    method:
      type: string
      enum: [GET, PUT, POST, DELETE]
      example: "GET"
    access_key:
      type: string
      example: "AKIAIOSFODNN7EXAMPLE"
    expires_at:
      type: string
      format: date-time
      example: "2023-01-15T11:30:00Z"
    created_at:
      type: string
      format: date-time
      example: "2023-01-15T10:30:00Z"

PresignedUrlsList:
  type: object
  properties:
    urls:
      type: array
      items:
        $ref: '#/PresignedUrlInfo'

CreatePresignedUrlRequest:
  type: object
  required:
    - bucket_name
    - object_key
    - access_key
  properties:
    bucket_name:
      type: string
      example: "my-bucket"
    object_key:
      type: string
      example: "file.txt"
    method:
      type: string
      enum: [GET, PUT, POST, DELETE]
      default: "GET"
      example: "GET"
    expires_in:
      type: integer
      minimum: 1
      maximum: 604800
      default: 3600
      example: 3600
      description: Expiration time in seconds (max 7 days)
    access_key:
      type: string
      example: "AKIAIOSFODNN7EXAMPLE"

CreatePresignedUrlResponse:
  type: object
  properties:
    url:
      type: string
      example: "/my-bucket/file.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20230115%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230115T103000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123&hash=def456"