Overloading

[mohsen1]

For response and operation overloading, we can use oneOf of JSON Schema. It's flexible and doesn't require a lot of changes in the specs.

Here is an example of how oneOf can solve response overloading:

---
swagger: '2.1'
info:
  version: 1.0.0
  title: Overloading example
paths:
  /:
    get:
      responses:
        200:
          oneOf:
            - description: Returns a string
              schema:
                type: string
            - description: Returns a number
              schema:
                type: integer

We can also use oneOf for operator overloading:

---
swagger: '2.1'
info:
  version: 1.0.0
  title: Overloading example
paths:
  /:
    get:
      oneOf:
        - description: with query param
          parameters:
            - name: name
              in: query
              description: name
              type: string
          responses:
            200:
              description: Returns a string
              schema:
                type: string
        - description: with header param
          parameters:
            - name: X-Name
              in: header
              description: name
              type: string
          responses:
            200:
              description: Returns a string
              schema:
                type: string

One thing that we should be careful about describing overloading is that Swagger should never describe the logic of how and why any of options will work.

[who]

+1

[vellotis]

+1

[drewish]

I think this duplicates a lot of the discussion on #333 and could be closed, but +1 from me as well.

[cabbonizio]

+1

[mrpotes]

+1

Lack of operator overloading is exactly the problem I've been having with Swagger :(

[jharmn]

Link to parent #565

[webron]

@mrpotes - can you give an example from your own use case? I'm having a bit of a hard time coming up with a real use case this applies to. The use cases I may be able to come up with should be resolved by something other than operation overloading (but should be resolved).

[mrpotes]

@webron Yep, sure.

For context, consider a RESTful HTTP user service, /users, which permits create, update, read, delete, patch using the usual HTTP verbs:

• POST to /users permits create with ID generation
• PUT to /users/{id} permits create/update with ID supplied
• GET to /users permits listing of users
• GET/DELETE/PATCH to /users/{id} permit read/delete/patch of a single user

However, for users there are other non-RESTful operations that you would also want to expose - for example, forgot password. We implement that service as a POST to /users?action=forgotPassword.

Both POST operations, the create and the forgot password, have distinct, fixed schemas and are best exposed as distinct Operations. Otherwise neither the payload nor the parameters can be represented to the consumer of the API description.

[mrpotes]

By the way, the link to parent issue #565 doesn't appear to have worked afaics

[webron]

@mrpotes Thanks for the explanation. I believe this relates more to what constitutes a unique operation than allowing multiple definitions per path - but the idea is clear. @jasonh-n-austin linked to the parameters meta issue, I'll link to the other one. We're in the process of organizing the tickets before diving into them, which is why you don't see any active work on the meta issues yet.

Parent issue: #574.

[handrews]

While this is too large of a change for the 3.x line, it is being addressed under the "Signature, please!" principle of OAS 4 Moonwalk.

Therefore I'm closing this in favor of the work happening in the Moonwalk repo.