swagger - 如何使用 OpenAPI 规范定义混合类型参数

Question

我遵循 OpenAPI (swagger) 规范来定义我的 API 端点。这是获取用户数据的端点定义的摘录:

"paths": {
  "/users/{id}": {
    "parameters": [
      {
        "name": "id",
        "in": "path",
        "description": "The user ID on which the operation will be executed.",
        "required": true,
        "type": "integer",
        "format": "int32",
      }
    ]
  }
}

但我想使用 /users/me 来获取登录用户的数据(因为在某些时候，登录用户的用户 ID 是未知的)。如您所见，me 是一个字符串，而不是一个整数，因此我找不到根据 OpenAPI 规范在参数定义中混合类型的方法。

有什么方法或解决方法可以做到这一点吗？我是否应该定义另一个端点 /users/me 并复制 /users/{id} 定义以满足此需求？

Answer 1

我认为有两种可能的方法:

1. 正如您所建议的，您可以在 /users/me 定义第二个端点，不带任何路径参数。 Swagger 应该允许这样做，因为 URI 字符串是不同的。 users/me 段与需要整数值的端点不匹配；整数也不匹配固定字符串 me。
2. 您还可以定义单个路径，将 {id} 参数键入为字符串，并使用 pattern允许“我”或整数的约束。

这是第二个选项的样子:

{
  "paths": {
    "/users/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "The user ID on which the operation will be executed.",
          "required": true,
          "type": "string",
          "pattern": "^[-+]?[1-9]\\d*$|^[Mm][Ee]$"
        }
      ]
    }
  }
}

注意事项:

• 正则表达式允许一个可选的前导 + 或 - 符号，后跟一个整数值。如果不需要有符号整数，可以删除 [-+]? 表达式。
• 这允许任意整数，没有任何范围限制，并且不允许有前导零。将其限制在 int32 范围内相当困惑，但如果您需要这样做也是可行的。
• 注意 \d(十进制数字)的转义反斜杠。 JSON 字符串需要这个。
• 正则表达式还允许 me 使用大小写的任意组合来替代整数​​。

至于是使用第一个还是第二个选项，这实际上取决于您的 API 和您的代码。如果 API 协定在句法上完全相同，则第二种选择的优点是只需要一个路径对象，因此您的代码中只有一个处理程序。

如果规则不同，例如/users/me 变体需要在 header 中传递 API key 或用户 token ，那么第一个选项可能更简洁。