Question

我正在为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，但是最好直接在规范中挑剔细微之处。

Answer 1

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

OpenAPI：如何表示一个可以完成所有工作的端点？

1 个答案: