Question: does swagger spec support root nodes

Hey there,

I am writing documentation for rails application. And I am struggling with root nodes in responses.

Here is the example to describe what I mean by that.

GET /orders/ # get all orders

{
  "orders": [
    {
      "id": 28,
      "customer_name": "Peter"
    },
    {
      "id": 29,
      "customer_name": "Tomas"
    }
  ]
}

I came up with the workaround and so far I was creating artificial model Orders, that reference real model Order.

paths:
  /orders:
    get:
      summary: Get all orders
      description: Get All orders
      responses:
        '200':
          description: An array of orders inside root node
          schema:
            type: object
            $ref: '#/definitions/Orders'

definitions:
  Orders:
    type: object
    required:
      - orders
    properties:
      orders:
        type: array
        items:
          $ref: '#/definitions/Order'

  Order:
    type: object
    properties:
      id:
        type: integer
        description: Unique identifier representing a specific order
      customer_name:
        type: string
        description: The customer that the order is for

But I guess there has to be better way to do it. Because this is not the only endpoint (for instance /order/:id has root node ‘order’ etc.). So I will have to have a lot of artificial models. So my question is.

How am I supposed to write specs for responses that contains root node?

Thank you for any ideas.

[jharmn]

This seems to fit in with #519. The ability to define a “collection” wrapper, which can be reused for various resources avoids creating bespoke ‘wrappers’ for each collection in a CRUD resource pattern.

That said, this example design is somewhat flawed from taking advantage from that type of approach…if orders were items, this would be a reusable collection format.

[fehguy]

Really not sure what the question is, apologies. You are going to always want to describe your Order object. If it’s stuffed inside another object, you have two choices:

1. Define a holding object, if it’s going to be reused across many places. That’s what is described in the first post with the Orders holder, which has an array of type order
2. Define the response in-line so that the order attribute points to the Order array:

responses:
  200:
    description: the order you wanted
    schema:
      type: object
      properties:
        order:
          type: array
          items:
            $ref: '#/definintions/Order'