BucketName:
  name: bucket
  in: path
  required: true
  description: Name of the S3 bucket
  schema:
    type: string
    pattern: '^[a-z0-9\-\.]+$'
    minLength: 3
    maxLength: 63
  example: "my-bucket"

ObjectKey:
  name: key
  in: path
  required: true
  description: Object key (file path) within the bucket
  schema:
    type: string
    maxLength: 255
  example: "folder/file.txt"
  style: simple
  explode: false

CredentialId:
  name: id
  in: path
  required: true
  description: Unique identifier for the credential
  schema:
    type: integer
    minimum: 1
  example: 1

Prefix:
  name: prefix
  in: query
  description: Limits the response to keys that begin with the specified prefix
  schema:
    type: string
    maxLength: 255
  example: "photos/"

Marker:
  name: marker
  in: query
  description: Specifies the key to start with when listing objects
  schema:
    type: string
    maxLength: 255
  example: "photos/2023/"

MaxKeys:
  name: max-keys
  in: query
  description: Maximum number of keys to return
  schema:
    type: integer
    minimum: 1
    maximum: 1000
    default: 1000
  example: 100

Delimiter:
  name: delimiter
  in: query
  description: Character used to group keys
  schema:
    type: string
    maxLength: 1
  example: "/"

PartNumber:
  name: partNumber
  in: query
  description: Part number for multipart upload (1-10,000)
  schema:
    type: integer
    minimum: 1
    maximum: 10000
  example: 1

UploadId:
  name: uploadId
  in: query
  description: Upload ID for multipart upload operations
  schema:
    type: string
    maxLength: 64
  example: "upload_12345_abcdef"

VersionId:
  name: versionId
  in: query
  description: Version ID of the object (if versioning is enabled)
  schema:
    type: string
    maxLength: 64
  example: "version_123"

ContentMD5:
  name: Content-MD5
  in: header
  description: MD5 digest of the request body
  schema:
    type: string
    pattern: '^[A-Za-z0-9+/]+=*$'
  example: "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="

ContentType:
  name: Content-Type
  in: header
  description: MIME type of the object
  schema:
    type: string
    maxLength: 255
    default: "application/octet-stream"
  example: "image/jpeg"

ContentLength:
  name: Content-Length
  in: header
  description: Size of the object in bytes
  schema:
    type: integer
    minimum: 0
  example: 1024000

Range:
  name: Range
  in: header
  description: Downloads the specified range bytes of an object
  schema:
    type: string
    pattern: '^bytes=\d+-\d*$'
  example: "bytes=0-1023"

IfMatch:
  name: If-Match
  in: header
  description: Return the object only if its ETag matches the specified value
  schema:
    type: string
  example: "\"9bb58f26192e4ba00f01e2e7b136bbd8\""

IfNoneMatch:
  name: If-None-Match
  in: header
  description: Return the object only if its ETag does not match the specified value
  schema:
    type: string
  example: "\"9bb58f26192e4ba00f01e2e7b136bbd8\""

IfModifiedSince:
  name: If-Modified-Since
  in: header
  description: Return the object only if it has been modified since the specified time
  schema:
    type: string
    format: date-time
  example: "Wed, 15 Jan 2023 10:30:00 GMT"

IfUnmodifiedSince:
  name: If-Unmodified-Since
  in: header
  description: Return the object only if it has not been modified since the specified time
  schema:
    type: string
    format: date-time
  example: "Wed, 15 Jan 2023 10:30:00 GMT"

CacheControl:
  name: Cache-Control
  in: header
  description: Specifies caching behavior for the object
  schema:
    type: string
  example: "max-age=3600"

ContentDisposition:
  name: Content-Disposition
  in: header
  description: Specifies presentational information for the object
  schema:
    type: string
  example: "attachment; filename=\"file.txt\""

ContentEncoding:
  name: Content-Encoding
  in: header
  description: Specifies what content encodings have been applied to the object
  schema:
    type: string
  example: "gzip"

ContentLanguage:
  name: Content-Language
  in: header
  description: Language the content is in
  schema:
    type: string
  example: "en-US"

Expires:
  name: Expires
  in: header
  description: Date and time when the object expires
  schema:
    type: string
    format: date-time
  example: "Wed, 15 Jan 2024 10:30:00 GMT"

ServerSideEncryption:
  name: x-amz-server-side-encryption
  in: header
  description: Server-side encryption algorithm to use
  schema:
    type: string
    enum: ["AES256", "aws:kms"]
  example: "AES256"

StorageClass:
  name: x-amz-storage-class
  in: header
  description: Storage class for the object
  schema:
    type: string
    enum: ["STANDARD", "REDUCED_REDUNDANCY", "GLACIER", "DEEP_ARCHIVE"]
    default: "STANDARD"
  example: "STANDARD"

Tagging:
  name: x-amz-tagging
  in: header
  description: Object tag set as a query string
  schema:
    type: string
  example: "key1=value1&key2=value2"

MetadataDirective:
  name: x-amz-metadata-directive
  in: header
  description: Specifies whether metadata is copied from the source object or replaced
  schema:
    type: string
    enum: ["COPY", "REPLACE"]
    default: "COPY"
  example: "REPLACE"

CopySource:
  name: x-amz-copy-source
  in: header
  description: Source bucket and object for copy operations
  schema:
    type: string
  example: "/source-bucket/source-object"

ACL:
  name: x-amz-acl
  in: header
  description: Canned ACL to apply to the object
  schema:
    type: string
    enum: ["private", "public-read", "public-read-write", "authenticated-read"]
    default: "private"
  example: "public-read"