Swagger - Formdata with a form-urlEncoded Item

Question

I'm trying to create a swagger document for my api and I'm a little stuck with something that I imagine is quite easy to achieve once you know how.

I have a endpoint that accepts a post as multipart/form-data (As it requires a file upload), however one of those items (pretend it's called "carParts" for the sake of this example), is a FormURLEncodedContent type that is a list of key/value pairs.

So the structure is something like:

carName:ford
carAge:20
carParts:wheels=4&horn=true&windscreen=broken

My problem is that I'm unsure how to express this ("carParts") in the swagger document.

The only way I can see to do it is to set the "carParts" item to a string type, but then I lose the point of swagger, in that I want "wheels", "horn" and "windscreen" to be explicit fields, not just a single form-urlEncoded string.

Is it possible to do this with swagger?

If not, I suppose the only other option is to change my api to just have the "carParts" items as a flat list rather than a structure (i.e. lose the "carParts" parent level and have the items just be other top level formdata items). It seems the most straight forward way, but it's a shame if I need to modify the api to achieve this (Not a major issue, just doesn't feel right).

Answer 1

This is possible in OpenAPI 3.0, but not in OpenAPI/Swagger 2.0.

In OpenAPI/Swagger 2.0, form fields cannot be objects, so you'll have to define carParts as a string or as an array of primitives.

In OpenAPI 3.0, you can have objects in form fields, and you can specify how these objects are serialized. There are not many examples currently, but I think your case can be described as follows:

paths:
  /something:
    post:
      requestBody:
        required: true
        content:

          multipart/form-data:
            # Form fields (carName, etc.) are defined as object properties
            schema:
              type: object
              properties:
                carName:
                  type: string
                carAge:
                  type: string
                carParts:
                  type: object
                  properties:
                    wheels:
                      type: integer
                    horn:
                      type: boolean
                    windscreen:
                      type: string
            # By default, the "carParts" object will be serialized as application/json,
            # but we can override the serialization method to be form-urlencoded
            encoding:
              carParts:
                contentType: application/x-www-form-urlencoded

Relevant part of the Specification: Special Considerations for multipart Content.