仅查询参数名称不同的路径

Question

我正在使用 swagger 编辑器记录一个现有 API，该 API 允许路径支持两个不同的请求，这两个请求仅在查询参数名称上有所不同。例如：

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

在这里，我支持对http://example.com/WS/Login?UserID=foo&Passoword=bar 和http://example.com/WS/Login?UserID=foo&Token=dubdu22r8dwjgd767dg 的请求。

swagger 编辑器不会显示上述 yaml 的任何错误，但它只会为 second 路径（具有 UserId 和 Token 查询参数的路径）生成文档，而不是两者。有人可以指出我哪里出错了吗？谢谢。

编辑：

如果我将第二个 /Login: 路径更改为（例如）/Login1:，那么我会在文档中看到这两个路径。虽然不是解决方案。

我还想到，我可以指定一个 /Login: 路径，其中包含必需的 UserID 参数和可选的 Password 和 Token 参数。但是我如何指定必须提供UserID 和Password 中的恰好一个？

Answer 1

你可以改用路径参数，试试：

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