在 Open API 中具有相同结构但格式不同的两个 API 端点

Question

我正在构建一个 API，其中我有以下两个端点 GET /documents/:documentId 和 GET /documents/types。我已经指定 documentId 的格式应该是 UUID，但是当我点击 types 端点时，系统会感到困惑并重定向到 documentId 端点。我有以下定义

文档编号：

components:
  parameters:
     documentId:
       name: documentId
       in: path
       description: The ID of a document to access.
       required: true
       schema:
         type: string
         format: uuid

第一个端点（缩写）：

/documents/{documentId}:
  get:
    description: Get a document.
    parameters:
      - $ref: '#/components/parameters/documentId'
    produces:
      - application/json

第二个端点（缩写）：

/documents/types:
  get:
    description: List supported document types.
    tags:
      - Documents
    produces:
      - application/json
    parameters:
      - $ref: '#/components/parameters/active'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/sort'

是否可以同时拥有这两个，或者它们是否不兼容，不能放在同一个 API 集合中？

Answer 1

可能是您列出它们的顺序。将 types 端点放在 {documentId}

上方

这是文档中的示例

https://editor.swagger.io/?_ga=2.56132843.1503379663.1608323465-793486363.1608323465

在 Open API 中具有相同结构但格式不同的两个 API 端点

Two API endpoints with same structure but different formats in Open API

swagger

openapi