我遵循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 回答
我认为有两种可能的方法可以做到这一点:
如您所建议,您可以在
/users/me
定义第二个 endpoints ,而不包含任何路径参数 . Swagger应该允许这样做,因为URI字符串是不同的 .users/me
段与期望整数值的 endpoints 不匹配;整数也不匹配固定字符串me
.您还可以定义单个路径,将
{id}
参数键入为字符串,其中pattern约束允许'me'或整数 .这是第二个选项的样子:
笔记:
正则表达式允许可选的前导
+
或-
符号,后跟一个整数值 . 如果您不需要有符号整数,则可以删除[-+]?
表达式 .这允许任意整数,没有任何范围限制,并且不允许前导零 . 将此限制为int32范围相当麻烦,但如果您需要这样做,则可能 .
注意
\d
(十进制数字)的转义反斜杠 . JSON字符串需要这个 .正则表达式还允许
me
作为整数的替代,使用大小写的任意组合 .至于是否使用第一个或第二个选项,它实际上取决于您的API和您的代码 . 如果API Contract 完全相同,从语法上讲,第二个选项的优点是只需要一个路径对象,因此代码中只有一个处理程序 .
如果规则不同,例如
/users/me
变体需要在标头中传递API密钥或用户令牌,然后第一个选项可能更清晰 .如果你对多路复用相同的api不感兴趣,那么最简单的解决方案就是将其分解为两个api .
例如 .
/current_user
路径甚至不需要任何参数,因为您选择实现的身份验证方案就足够了 .