SwaggerHub API datetime参数格式验证异常求助

问题详情 #

API请求传入2021-01-30T08:30:00格式的时间参数时，持续收到400错误响应：

{
    "type": "about:blank",
    "title": "Bad Request",
    "detail": "'2021-01-30T08:30:00' is not a 'date-time'\n\nFailed validating 'format' in schema:\n    {'format': 'date-time', 'type': 'string'}\n\nOn instance:\n    '2021-01-30T08:30:00'",
    "status": 400
}

OpenAPI配置中参数定义如下（以start_timestamp为例）：

parameters:
  - in: query
    name: start_timestamp
    required: true
    schema:
      type: string
      format: date-time

已完成排查：确认时间字符串无多余字符/空格，验证器基础配置正常，仍无法通过校验。

原因分析 #

OpenAPI 3.0规定的date-time格式严格遵循RFC 3339标准，要求时间字符串必须包含时区信息——要么以Z表示UTC时区，要么携带±HH:MM的时区偏移。你当前使用的YYYY-MM-DDTHH:MM:SS格式缺少时区部分，不符合规范，因此被验证器拦截。

解决方案 #

方案1：修改请求时间格式（推荐） #

为时间字符串添加时区信息，示例：

• UTC时区：2021-01-30T08:30:00Z
• 东八区（北京时间）：2021-01-30T08:30:00+08:00

方案2：自定义正则匹配（兼容无时区格式） #

如果API业务逻辑不需要时区，或必须兼容现有无时区的请求格式，可以替换format: date-time为自定义正则表达式，精准匹配你的时间格式：

parameters:
  - in: query
    name: start_timestamp
    required: true
    schema:
      type: string
      pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$'

方案3：调整验证器严格度（不推荐） #

部分OpenAPI验证工具支持调整date-time的校验严格度，允许无时区格式通过。但这种方式违反OpenAPI官方规范，可能引发后续API兼容性问题，不建议采用。

内容的提问来源于stack exchange，提问作者user23353322