Swagger.next: Let's not use hashes anymore

[mohsen1]

Putting paths and operations in a hash made all sort of problems. The biggest problem is keeping order status of paths and operations. Tags can help organize the paths and operations but that's not enough. Most of people expect Swagger document keep it's order status when they are authoring one.
Other problem with using hashes is that we are using keys as a data storage. This makes it impossible to have other keys in paths or operation because every key is a path or operation.

Lets use arrays for the next version and make life easier for everyone. It will not make specs uglier. Here is an example:

# Example YAML for the bare minimum of required elements
# See petstore.yaml for a more comprehensive example
swagger: '3.0'
info:
  version: "1.0.0"
  title: petstore
paths:
  - 
    path: /pets # maybe path can have multiple endpoints like `path: [ "/pets", "/animals"]
    consumes:  # path level consumes 
      - "text/html"
    operations:
      - method: get # maybe we can define a batch of operations in one operation i.e. `methods: [ "post", "head"]
        responses:
          - 
            code: "200" # ability to have responses defined by code OR other means (solving response overloading issue)
            description:  Describe the 200 response in more detail

[webron]

There's a reason why hashes were introduces instead of array, and that was to enforce uniqueness. With arrays, you can have duplicate paths/operations and that makes the validation that much more difficult.

I'm not sure I understand your comment regarding have other keys other than paths or operations, since we on one hand we don't really need to allow additional keys, and on the other, we actually allow them with vendor extensions even today.

As for the ordering, that's been thoroughly discussed in the Swagger 2.0 work group. Ordering is a presentation issue and not a documentation one. Swagger-UI allows you to manipulation the paths and operation ordering and that should be enough.

[mohsen1]

1. Uniqueness can be enforced by Schema
2. Hashes made it impossible to have consumes for a path for example. This is not a vendor extension
3. Ordering is not only UI issue. For example in a testing scenario, the test runner might want to test some endpoints first.
4. Most of tools had to do another phase of sorting to get around this. For example in the editor I had to write this module to make it work.

I think using hashes was a bad decision. It's up to WG to make decision about it but we should look into this issue for the next version.

[webron]

1. Actually, no, uniqueness can't be enforced by schema.
2. It's possible to add consumes for a path. We just didn't do it.
3. At the moment, it's not within Swagger's scope to describe API flows. REST APIs are intended to be stateless and as such any flow that's introduced is basically artificial. That said, it doesn't mean it's not common to have such a use case, it's just not something we aimed to solve with Swagger. I think that falls out of scope for the basic Swagger documentation but it doesn't mean we won't support it by other means.
4. I don't know how you arrived to the conclusion that 'most' tools had to do it. I understand that presentation tools require to do it, and that's fine given my original comment.

And to be clear, I'm all for revisiting decisions and changing them as needed, though personally here I don't see a reason for it.

[mohsen1]

Lets keep this open for next version discussions. Hopefully we can talk about this in details at some point :)

[fehguy]

Reference #560

[fehguy]

@OAI/tdc propose closing this with no action, please approve / reject

[webron]

Voting to close.

[DavidBiesack]

I see this as tied to #146 for which arrays instead of maps (hashes) was proposed.
is there a solution for #146 that does not change the paths map to an array?

[ePaul]

@DavidBiesack for #146 I would prefer not to repeat the same path twice, but have the consumes/produces distinction under the operation level.