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

我认为有两种可能的方法可以做到这一点：

根据您的建议，您可以在/users/me定义第二个端点，而不包含任何路径参数。 Swagger应该允许这样做，因为URI字符串是不同的。 users/me段与期望整数值的端点不匹配;也不是整数与固定字符串me匹配。
您还可以定义单个路径，{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变体需要在标头中传递API密钥或用户令牌，然后第一个选项可能更清晰。

Answer 2

如果你对多路复用相同的api不感兴趣，那么最简单的解决办法就是把它分解成两个api。

例如

/users/{id}
/current_user

/current_user路径甚至不需要任何参数，因为您选择实施的身份验证方案就足够了。

如何使用OpenAPI规范

2 个答案: