cancel
Showing results for 
Search instead for 
Did you mean: 

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

SOLVED
ehudson
Occasional Visitor

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

1 ACCEPTED SOLUTION

Accepted Solutions
HKosova
Moderator

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

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.


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️

View solution in original post

1 REPLY 1
HKosova
Moderator

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

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.


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️

View solution in original post

New Here?
Join us and watch the welcome video:
Announcements
Top Kudoed Authors