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.