Paths that differ only in query parameter names

Question

I'm using the swagger editor to document an existing API that allows a path to support two different requests that differ only in their query parameter names. For example:

swagger: '2.0'
info:
  title: example
  version: 1.0.0
host: example.com
schemes:
  - http
basePath: /WS
paths:
  /Login:
    post:
      summary: Login
      description: |
        Log in
      parameters:
        - name: UserID
          in: query
          description: User ID
          required: true
          type: string
        - name: Password
          in: query
          description: User password
          required: true
          type: string
      responses:
        '200':
          description: Success
  /Login:
    post:
      summary: Login
      description: |
        Log in
      parameters:
        - name: UserID
          in: query
          description: User ID
          required: true
          type: string
        - name: Token
          in: query
          description: Authentication token
          required: true
          type: string
      responses:
        '200':
          description: Success

Here I support requests to http://example.com/WS/Login?UserID=foo&Passoword=bar and http://example.com/WS/Login?UserID=foo&Token=dubdu22r8dwjgd767dg.

The swagger editor doesn't show any errors for the above yaml, but it only generates documentation for the second path (the one with UserId and Token queryparams), not both. Can someone point out where I'm going wrong? Thanks.

Edit:

If I change the second /Login: path to (for example) /Login1: then I see both paths in the documentation. Not a solution though.

It also occurs to me that I could specify one /Login: path with a required UserID parameter and optional Password and Token parameters. But how do I specify that exactly one of UserID and Password must be supplied?

Answer 1

You can use path parameters instead, try with:

swagger: '2.0'
info:
  title: example
  version: 1.0.0
host: example.com
schemes:
  - http
basePath: /WS
paths:
  /Login?UserID={id}&Password={password}:
    post:
      summary: Login
      description: Log in
      parameters:
        - name: id
          in: path
          description: User ID
          required: true
          type: string
        - name: password
          in: path
          description: User password
          required: true
          type: string
      responses:
        '200':
          description: Success
  /Login?UserID={id}&Token={token}:
    post:
      summary: Login
      description: Log in
      parameters:
        - name: id
          in: path
          description: User ID
          required: true
          type: string
        - name: token
          in: path
          description: Authentication token
          required: true
          type: string
      responses:
        '200':
          description: Success