OpenAPI：如何表示一个可以做所有事情的端点？ [复制]

Posted 2023-02-16

【中文标题】OpenAPI：如何表示一个可以做所有事情的端点？ [复制]

【英文标题】：OpenAPI: How to represent one endpoint that does everything? [duplicate]

【发布时间】：2019-09-10 00:04:05

【问题描述】：

我正在为 older-style XML API 制定 OpenAPI 3 规范，该规范为所有查询提供一个端点。它总是返回相同的数据结构，但根据请求的查询参数，将填充不同的响应字段。事实上，散文 API 规范建议仅将 HTTPS 用于登录，而将 HTTP 用于其他所有内容。 （不要拍信使，我不拥有API，我只是一个客户。）

我想在规范中区分那些语义不同的请求，例如：

paths:
  /:
    get:
      operationId: login
      parameters:
      - name: username
      - name: password
    get:
      operationId: getCallsign
      parameters:
      - name: s
        description: session token
     - name: callsign
        description: perform a callsign info lookup
    get:
      operationId: getDxcc
      parameters:
      - name: s
        description: session token
      - name: dxcc
        description: perform a DXCC info lookup

但是，这似乎不受支持。路径和方法的组合必须是唯一的，所以GET /必须是单个操作。

paths:
  /:
    get:
      operationId: doEverything
      parameters:
      - name: username
      - name: password
      - name: s
        description: session token
      - name: callsign
        description: perform a callsign info lookup
      - name: dxcc
        description: perform a DXCC info lookup

有没有办法在一个端点上分离这些不同的操作？如果没有，我可以在生成的库上编写一个瘦客户端库，这使得 API 的使用更加清晰，但最好直接在规范中梳理细节。

【问题讨论】：

谢谢海伦。我没有足够的声誉将其设置为重复，但答案确实解决了我的问题。

【参考方案1】：

正如 Helen 所指出的，this answer 解决了这个问题：Swagger/OpenAPI 中的操作由 HTTP 动词和路径作为键，因此不能分解执行多个不同操作的单个端点。它必须是一个单一的大型操作。