node.js – 允许swagger查询参数为字符串或整数数组

2023年3月9日 451次阅读

在使用swagger2(openAPI)构建rest api时,我想允许查询param 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.

最佳答案 我认为您需要的是与JSON Schema提供的关键字类似的anyOf或oneOf关键字,以便您可以将station_id参数的类型定义为数字或字符串. OpenAPI 3.0支持anyOf和oneOf,但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.

点赞