Skip to content
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

Closed
mirrec opened this issue Dec 10, 2015 · 9 comments
Closed

Question: does swagger spec support root nodes #522

mirrec opened this issue Dec 10, 2015 · 9 comments
Labels
Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk

Comments

@mirrec
Copy link

mirrec commented Dec 10, 2015

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.

@fehguy
Copy link
Contributor

fehguy commented Dec 10, 2015

You would do this in your definition if you don't want an Orders object:

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'

@mirrec
Copy link
Author

mirrec commented Dec 10, 2015

Thank you @fehguy for your suggestion.

But now I lost root node name orders (and order in /orders/:id endpoint) and it also changes response class in swagger UI.
from:
with_root_node

to:
without_root_node

So this is not correct I guess. Any other suggestions?

@fehguy
Copy link
Contributor

fehguy commented Dec 10, 2015

I misread your post. It looks like what you described is a good way to do so, if you want the orders key to hold the array. Sorry for the confusion!

@azuby
Copy link

azuby commented Dec 11, 2015

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.

@webron
Copy link
Member

webron commented Dec 11, 2015

The problem isn't really clear, so not sure what support is missing.

@fehguy
Copy link
Contributor

fehguy commented Dec 11, 2015

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'

@jharmn
Copy link
Contributor

jharmn commented Jan 8, 2016

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
Copy link
Contributor

fehguy commented Mar 1, 2016

Parent issues #579, #586

@handrews handrews added the Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk label Jan 26, 2024
@handrews
Copy link
Member

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk
Projects
None yet
Development

No branches or pull requests

6 participants