{"action":"created","issue":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/522","labels_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/522/labels{/name}","comments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/522/comments","events_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/522/events","html_url":"https://github.com/OAI/OpenAPI-Specification/issues/522","id":121462726,"number":522,"title":"Question: does swagger spec support root nodes","user":{"login":"mirrec","id":544111,"avatar_url":"https://avatars.githubusercontent.com/u/544111?v=3","gravatar_id":"","url":"https://api.github.com/users/mirrec","html_url":"https://github.com/mirrec","followers_url":"https://api.github.com/users/mirrec/followers","following_url":"https://api.github.com/users/mirrec/following{/other_user}","gists_url":"https://api.github.com/users/mirrec/gists{/gist_id}","starred_url":"https://api.github.com/users/mirrec/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mirrec/subscriptions","organizations_url":"https://api.github.com/users/mirrec/orgs","repos_url":"https://api.github.com/users/mirrec/repos","events_url":"https://api.github.com/users/mirrec/events{/privacy}","received_events_url":"https://api.github.com/users/mirrec/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":7,"created_at":"2015-12-10T11:24:58Z","updated_at":"2016-01-08T21:16:23Z","closed_at":null,"body":"Hey there,\r\n\r\nI am writing documentation for rails application. And I am struggling with root nodes in responses.\r\n\r\nHere is the example to describe what I mean by that.\r\n\r\n`GET /orders/` # get all orders\r\n```json\r\n{\r\n  \"orders\": [\r\n    {\r\n      \"id\": 28,\r\n      \"customer_name\": \"Peter\"\r\n    },\r\n    {\r\n      \"id\": 29,\r\n      \"customer_name\": \"Tomas\"\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\nI came up with the workaround and so far I was creating artificial model Orders, that reference real model Order.\r\n\r\n```yaml\r\npaths:\r\n  /orders:\r\n    get:\r\n      summary: Get all orders\r\n      description: Get All orders\r\n      responses:\r\n        '200':\r\n          description: An array of orders inside root node\r\n          schema:\r\n            type: object\r\n            $ref: '#/definitions/Orders'\r\n\r\ndefinitions:\r\n  Orders:\r\n    type: object\r\n    required:\r\n      - orders\r\n    properties:\r\n      orders:\r\n        type: array\r\n        items:\r\n          $ref: '#/definitions/Order'\r\n          \r\n  Order:\r\n    type: object\r\n    properties:\r\n      id:\r\n        type: integer\r\n        description: Unique identifier representing a specific order\r\n      customer_name:\r\n        type: string\r\n        description: The customer that the order is for\r\n```\r\n\r\nBut 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.\r\n\r\nHow am I supposed to write specs for responses that contains root node?\r\n\r\nThank you for any ideas."},"comment":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/comments/170125845","html_url":"https://github.com/OAI/OpenAPI-Specification/issues/522#issuecomment-170125845","issue_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/522","id":170125845,"user":{"login":"jasonh-n-austin","id":1305160,"avatar_url":"https://avatars.githubusercontent.com/u/1305160?v=3","gravatar_id":"","url":"https://api.github.com/users/jasonh-n-austin","html_url":"https://github.com/jasonh-n-austin","followers_url":"https://api.github.com/users/jasonh-n-austin/followers","following_url":"https://api.github.com/users/jasonh-n-austin/following{/other_user}","gists_url":"https://api.github.com/users/jasonh-n-austin/gists{/gist_id}","starred_url":"https://api.github.com/users/jasonh-n-austin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jasonh-n-austin/subscriptions","organizations_url":"https://api.github.com/users/jasonh-n-austin/orgs","repos_url":"https://api.github.com/users/jasonh-n-austin/repos","events_url":"https://api.github.com/users/jasonh-n-austin/events{/privacy}","received_events_url":"https://api.github.com/users/jasonh-n-austin/received_events","type":"User","site_admin":false},"created_at":"2016-01-08T21:16:23Z","updated_at":"2016-01-08T21:16:23Z","body":"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. \r\n\r\nThat 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."}}