首页 文章

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

提问于
浏览
3

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

"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对于已登录的用户来说是未知的) . 你可以看到我是一个字符串,而不是一个整数,所以我找不到根据OpenAPI规范在参数定义中混合类型的方法 .

有没有办法或解决方法呢?我应该定义另一个 endpoints / users / me并复制/ users / 定义以满足此需求吗?

2 回答

  • 1

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

    • 如您所建议,您可以在 /users/me 定义第二个 endpoints ,而不包含任何路径参数 . Swagger应该允许这样做,因为URI字符串是不同的 . users/me 段与期望整数值的 endpoints 不匹配;整数也不匹配固定字符串 me .

    • 您还可以定义单个路径,将 {id} 参数键入为字符串,其中pattern约束允许'me'或整数 .

    这是第二个选项的样子:

    {
      "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 Contract 完全相同,从语法上讲,第二个选项的优点是只需要一个路径对象,因此代码中只有一个处理程序 .

    如果规则不同,例如 /users/me 变体需要在标头中传递API密钥或用户令牌,然后第一个选项可能更清晰 .

  • 3

    如果你对多路复用相同的api不感兴趣,那么最简单的解决方案就是将其分解为两个api .

    例如 .

    /users/{id}
    /current_user
    

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

相关问题