如何在OpenAPI中定义POST请求体中的位置参数？

你的问题在于用items数组定义不同位置的元素类型，这不符合对应OpenAPI版本的规范。要定义这种固定结构的数组（元组），需根据你使用的OpenAPI版本选择写法：

情况1：使用OpenAPI 3.1（推荐，支持JSON Schema 2020-12） #

OpenAPI 3.1引入prefixItems字段专门用于定义元组的每个位置元素类型，搭配minItems和maxItems限定数组长度，确保请求体严格匹配3个元素的结构：

"requestBody": {
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "prefixItems": [
          { "type": "string" },
          { "type": "integer" },
          {
            "type": "array",
            "items": { "type": "integer" }
          }
        ],
        "minItems": 3,
        "maxItems": 3,
        "additionalItems": false // 禁止添加定义外的额外元素
      }
    }
  }
}

情况2：使用OpenAPI 3.0（基于JSON Schema Draft 04） #

OpenAPI 3.0兼容Draft 04的写法，允许用items数组定义元组结构，同样需要minItems和maxItems来固定数组长度：

"requestBody": {
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": [
          { "type": "string" },
          { "type": "integer" },
          {
            "type": "array",
            "items": { "type": "integer" }
          }
        ],
        "minItems": 3,
        "maxItems": 3
      }
    }
  }
}

关键说明 #

• prefixItems（3.1）或items数组（3.0）：按顺序指定每个位置元素的类型
• minItems/maxItems：强制数组长度与定义一致，避免多传或少传元素
• additionalItems: false（3.1）：明确禁止超出定义的额外元素，提升校验严谨性

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