Incorrect body for PutObject in Amazon S3

[kennyjwilli]

According to the PutObject operation documented in the AWS S3 Swagger doc here, the body takes the following format:

- name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              Body:
                description: Object data.
                type: string
              x-amz-meta-:
                description: A map of metadata to store with the object in S3.
                type: object
                additionalProperties:
                  $ref: '#/definitions/MetadataValue'

According the the Amazon HTML REST API reference, the x-amz-meta- should be included in the request header. The Swagger doc states it is a body parameter. The Swagger doc is incorrect.

[MikeRalphson]

Again, would appreciate thoughts from @pimterry

[pimterry]

This happens mainly because we don't understand the headers location used in the S3 SDK definition: https://github.com/aws/aws-sdk-js/blob/master/apis/s3-2006-03-01.normal.json#L2168-L2173. For parameters with no location (or no understood location), we assume they're part of the body parameter. Logic is here, note that it only includes header, not headers.

To be clear though, this isn't just a header that's in the wrong place. This field is actually a header prefix. The docs use the example of x-amz-meta-author: Janet to set author: janet as metadata on an S3 object.

That makes this much harder, because I don't think there is any clear way to describe this parameter in OpenAPI v2, or even in v3. It looks like wildcard parameter support like this (i.e. x-amz-meta-*) just isn't possible: https://github.com/OAI/OpenAPI-Specification/issues/1017.

Any idea on ways to work around or describe this @MikeRalphson? Was there a specific format for this you were expecting @kennyjwilli?

[Xuanwo]

Maybe we could move x-amz-meta- to header and let tools to handle an object in header.