6

I have a multipart/form-data POST in an API endpoint which takes some key/value strings, and a file upload via the key files.

I believe I have defined it correctly in OpenAPI;

"requestBody": {
  "required": true,
  "content": {
    "multipart/form-data": {
      "schema": {
        "properties": {
          "file": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "binary"
            }
          },
          "myKey1": {
            "type": "string"
          },
          "myKey2": {
            "type": "string"
          }
        }
      },
      "examples": {
        "value": ?
      }
    }
  }
},

However, I am unsure how I can describe an example for a multipart/form-data in the examples field.

I assume I don't need to represent the file (although that would be a bonus) but just the myKey1 and myKey2 keys and values.

myol
  • 8,857
  • 19
  • 82
  • 143

1 Answers1

5

Your OAS definition seems to be correct. You can define the examples as shown below:

      "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "example": [
                      {
                        "externalValue": "http://www.africau.edu/images/default/sample.pdf"
                      }
                    ]
                  },
                  "myKey1": {
                    "type": "string",
                    "example": "myKey1Example"
                  },
                  "myKey2": {
                    "type": "string",
                    "example": "myKey2Example"
                  }
                }
              }
            }
          }
        },

externalValue can be added to point the sample file URL in Open API Specification. This is only for the document purpose.

However, it will not be displayed in the swagger-ui as swagger-ui does not support it yet. It is tracked in [1].

[1] https://github.com/swagger-api/swagger-ui/issues/5433

Vithursa Mahendrarajah
  • 1,194
  • 2
  • 15
  • 28
  • Ok thanks, I understand the use case for `example` but can you provide a use case for an `examples` array? – myol Aug 25 '21 at 07:55
  • It's only used to denote that the API consumer can upload more than one files to this resource – Vithursa Mahendrarajah Aug 25 '21 at 08:45
  • Are you sure? From how the specification reads, it seems like `examples` is an array of different examples – myol Aug 25 '21 at 09:06
  • `externalValue` is only supported in media type `examples` (plural `exampleS`), it's not supported in schema/property `example`. – Helen Aug 25 '21 at 09:15
  • @myol, Sorry I was under impression that you are asking about the example array in this questions. Yes, `examples` is used to provide multiple example for a parameter. You can get more info [here](https://swagger.io/docs/specification/adding-examples/). – Vithursa Mahendrarajah Aug 25 '21 at 09:45