在使用 swagger2 (openAPI) 构建 rest api 时,我想让查询参数 station_id 支持以下内容:
- ?station_id=23(返回站 23)
- ?station_id=23,45(返回站 23 和 45)
- ?station_id=[3:14](返回站 3 到 14)
- ?station_id=100%(%s 作为通配符,返回 1001, 10049 等。)
我使用以下 swagger 定义(字符串数组)来尝试实现此目的:
parameters:
- name: station_id
in: query
description: filter stations by station_id
required: false
type: array
items:
type: string
使用此定义,除了 ?station_id=23 之外的所有先前示例都有效,因为 swagger 验证失败并显示以下消息:
{
"message": "Validation errors",
"errors": [
{
"code": "INVALID_REQUEST_PARAMETER",
"errors": [
{
"code": "INVALID_TYPE",
"params": [
"array",
"integer"
],
"message": "Expected type array but found type integer",
"path": [],
"description": "filter stations by station_id"
}
],
"in": "query",
"message": "Invalid parameter (station_id): Value failed JSON Schema validation",
"name": "station_id",
"path": [
"paths",
"/stations",
"get",
"parameters",
"0"
]
}
]
}
请注意,如果我引用 station_id 之类的 ?station_id='23' 验证通过并且我得到正确的响应。但我真的不想使用引号。联合类型之类的东西有助于解决这个问题,但据我所知,它们不受支持。
我还有另一个端点/stations/{id} 可以处理单个 id 的情况,但仍然有许多其他(非主键)数字字段我想以上面指定的方式过滤。例如 station_latitude。
有任何解决方法的想法 - 也许我可以以某种方式使用模式(正则表达式)?如果 swagger 定义中没有解决方法,是否有办法调整或绕过验证器?这是一个使用 swagger-node 的 nodejs 项目我升级了swagger-express-mw的版本到 0.7.0。
最佳答案
我认为您需要的是 anyOf
或 oneOf
关键字,类似于 JSON Schema 提供的关键字,以便您可以定义 的类型station_id
参数可以是数字或字符串。 anyOf
和 oneOf
在 OpenAPI 3.0 中受支持,但在 2.0 中不受支持。 OpenAPI 3.0 定义如下所示:
openapi: 3.0.0
...
paths:
/something:
get:
parameters:
- in: query
name: station_id
required: true
explode: false
schema:
oneOf:
- type: integer # Optional? Array is supposed to cover the use case with a single number
example: 23
- type: array
items:
type: integer
minItems: 1
example: [23, 45]
- type: string
oneOf:
- pattern: '^\[\d+:\d+]$'
- pattern: '^\d+%$'
# or using a single pattern
# pattern: '^(\[\d+:\d+])|(\d+%)$'
example: '[3:14]'
作为替代方案,您也许可以添加 sortBy
、skip
和 limit
参数以保持类型统一。例如:?sortBy=station_id&skip=10&limit=10
将仅检索站 10 - 20。
关于node.js - 允许 swagger 查询参数为字符串或整数数组,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/41271816/