Forum Discussion

ehudson's avatar
ehudson
Occasional Visitor
4 years ago

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

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

  • 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.

  • HKosova's avatar
    HKosova
    SmartBear Alumni (Retired)

    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.