Skip to content

Question: does swagger spec support root nodes #522

@mirrec

Description

@mirrec

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Moved to MoonwalkIssues that can be closed or migrated as being addressed in Moonwalk

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions