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?

Related (or duplicate of): [How to define mutually exclusive query parameters in Swagger (OpenAPI)?](https://stackoverflow.com/questions/21134029/how-to-define-mutually-exclusive-query-parameters-in-swagger-openapi) — Helen, Mar 09 '18 at 17:46

score 0 · Accepted Answer · answered Sep 18 '15 at 18:11

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

Yes, that was the problem: I didn't include the queryparams in the paths. Can't believe I missed that! Thanks for your help! — Andy Johnson, Sep 21 '15 at 16:34
This is not a valid Swagger 2.0 spec. Query parameters are not allowed in paths. — Helen, Nov 15 '16 at 10:01

Paths that differ only in query parameter names

1 Answers1