-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Question: does swagger spec support root nodes #522
Comments
You would do this in your definition if you don't want an paths:
/orders/{id}:
get:
description: gets a single order
parameters:
- name: id
in: path
type: integer
format: int32
responses:
200:
description: the order you wanted
schema:
$ref: '#/definintions/Order'
/orders:
get:
summary: Get all orders
description: Get All orders
responses:
'200':
description: An array of orders inside root node
schema:
type: array
items:
$ref: '#/definitions/Order' |
Thank you @fehguy for your suggestion. But now I lost root node name So this is not correct I guess. Any other suggestions? |
I misread your post. It looks like what you described is a good way to do so, if you want the |
We have the same issue. This seems like a feature that Swagger really should support. This is a fairly common pattern for modern APIs now. Creating an Orders object seems more akin to a hack than a solution. |
The problem isn't really clear, so not sure what support is missing. |
Really not sure what the question is, apologies. You are going to always want to describe your
responses:
200:
description: the order you wanted
schema:
type: object
properties:
order:
type: array
items:
$ref: '#/definintions/Order' |
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 |
Discussions relevant to this general idea are happening in the Moonwalk project, specifically: Since I cannot imagine that we could fit this into the 3.x line (too much change would be required), I'm going to mark this as "moved to moonwalk." Please feel free to join the conversation there! |
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 ordersI came up with the workaround and so far I was creating artificial model Orders, that reference real model Order.
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.
The text was updated successfully, but these errors were encountered: