How to nest a JSON payload under a named parameter in open api 3.0

Question

I'm trying to describe an API endpoint that receives a PUT request with the following JSON payload:

{
  "product": {
    "name: "foo",
    "brand": "bar"
  }
}

Here is a sample of the definition:

components:
  schemas:
    Product:
      type: object
      required:
        - name
        - brand
      properties:
        name:
          type: string
        brand:
          type: string
paths:
  /products/{id}:
    parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
    put:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'

However, this produces the following JSON payload (it's missing the "product" key):

{
  "name: "foo",
  "brand": "bar"
}

I tried this:

      parameters:
        - name: product
          in: body
          schema:
            type: object
            properties:
              product:
                type: object
                schema:
                  $ref: '#/components/schemas/Product'

But that doesn't work. Any ideas?

score 0 · Accepted Answer · answered Oct 04 '19 at 13:56

Your second example is almost correct, just change this part

          schema:
            type: object
            properties:
              product:
                type: object
                schema:
                  $ref: '#/components/schemas/Product'

to

          schema:
            type: object
            properties:
              product:
                $ref: '#/components/schemas/Product'

Note the $ref is used directly under the property name.

How to nest a JSON payload under a named parameter in open api 3.0

1 Answers1