OpenAPI Example multipart form data

Question

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.

Answer 1

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