Using objects in formData in OpenAPI 2.0 (how to $ref?)

Open Source Swagger OS
, ,
1

Originally posted by ehudson on April 07, 2021

Hi,

Using OpenAPI 2.0, I have a number of parameters for a post operation. I can’t figure out how to handle object types, and in particular using $ref to their properties. For a string parameter, for example, I do:

- name: parameterName
  description: parameterDescription
  in: formData
  required: true
  type: string

But for an object parameter I thought I could do something like:

- name: parameterName
  description: parameterDescription
  in: formData
  required: true
  type: object
  properties:
    allOf:
      - $ref: '#/definitions/MyParameterDescription'

but it, and everything else I’ve tried, don’t seem to work. That is, Stoplight gives me errors like “property should have required property ‘schema’” or “$ref cannot be placed next to any other properties” or (when I use ‘schema’) it tells me that all the other properties shouldn’t be there, …

What is the proper way of doing this? In case it matters, my definition looks something like:

definitions:
  MyParameterDescription:
    properties:
      first_property:
        description: ...

I’m pretty sure it is ok because if I have an array and declare items to ref to this it works fine.

Thanks for any help you can offer!

PS I’m completely new to this so apologies if this is obvious but I haven’t been able to find examples - I also appreciate any pointers to places I should be looking

2

Originally posted by HKosova on April 07, 2021

Hi ehudson,

OpenAPI 2.0 does not support objects and $ref in form data. You need OpenAPI 3.0 for that. Here’s an example that you can test in the Swagger Editor:

openapi: 3.0.0
info:
  title: Object in form data
  version: 1.0.0
servers:
  - url: https://httpbin.org/anything

paths:
  /something:
    post:
      requestBody:
        content:
          application/x-www-form-urlencoding:
            schema:
              type: object
              properties:
                parameterName:
                  $ref: '#/components/schemas/MyParameterDescription'
      responses:
        '200':
          description: ok

components:
  schemas:
    MyParameterDescription:
      type: object
      description: An object sent inside a form field
      properties:
        first_property:
          description: ...

For more OpenAPI 3.0 examples, see the “Form Data” section in Describing Request Body.