Open API 中结构相同但格式不同的两个 API 端点答案

【问题标题】：Two API endpoints with same structure but different formats in Open APIOpen API 中结构相同但格式不同的两个 API 端点
【发布时间】：2020-12-18 20:29:21
【问题描述】：

我正在构建一个 API，其中有以下两个端点 GET /documents/:documentId 和GET /documents/types。我已经指定 documentId 的格式应该是 UUID，但是当我点击类型端点时，系统会感到困惑并重定向到 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 集中不能兼容？

【问题讨论】：

OpenAPI 规范说必须首先匹配 /documents/{documentId} 等模板路径，因此这是您的服务器的问题。你的服务器是用什么框架/库构建的？
在一个不相关的注释中，您混合了 OAS2 和 OAS3 语法（produces 是 OAS2 关键字，但 #/components/parameters 是 OAS3）。确保您的定义有效。您可以检查editor.swagger.io中的语法。
谢谢@Helen，原来是端点的顺序，但感谢您指出混合语法。顺便说一句，我们的服务器是使用带有 express 的 NodeJS 构建的，但是我们有一个自定义解析器，以便我们可以将每个端点的 Express 代码与相关端点存储在同一目录中。
顺序无关紧要。我建议您使用实现路由的 Node.js 或 express 框架打开一个问题。

标签： swagger openapi

【解决方案1】：

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

这是文档中的一个示例

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

【讨论】：

这行得通。我将顺序更改为先放置 /documents/types 并得到了正确的响应。