Swagger UI未正确处理POST请求JSON体可选键问题求助

针对你遇到的问题——Swagger UI在开启jsonEditor后，会自动给可选的数组字段（如idsUser、idsUsergroup）填充空数组，而非只发送必填的name字段，我们可以从Joi Schema配置和hapi-swagger生成逻辑两个层面来解决：

1. 调整Joi Schema，标记可选字段为可空 #

hapi-swagger默认会根据Joi Schema生成Swagger定义，但对于可选数组字段，需要明确告诉它这些字段可以不存在（而非存在但为空）。你可以给可选数组字段添加allow(null)和meta({ swagger: { nullable: true } })，让hapi-swagger在生成的swagger.json里标记这些字段为可空：

Joi.object().keys({
  request: Joi.object().keys({
    name: Joi.string().required(),
    idsUser: Joi.array().items(Joi.string())
      .optional() // 明确标记为可选（默认即为可选，添加后更清晰）
      .allow(null) // 允许字段值为null
      .meta({ swagger: { nullable: true } }), // 告知hapi-swagger生成可空标记
    idsUsergroup: Joi.array().items(Joi.string())
      .optional()
      .allow(null)
      .meta({ swagger: { nullable: true } }),
  }),
});

调整后生成的swagger.json中，Model 208的定义会新增"nullable": true标记：

"Model 208": {
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "idsUser": {
      "$ref": "#/definitions/Model 13",
      "type": "array",
      "x-alternatives": [...],
      "nullable": true // 新增的可空标记
    },
    "idsUsergroup": {
      "$ref": "#/definitions/Model 13",
      "type": "array",
      "x-alternatives": [...],
      "nullable": true // 新增的可空标记
    }
  },
  "required": ["name"]
}

Swagger UI的jsonEditor识别到nullable: true后，就不会自动填充空数组到这些字段，只会保留必填的name。

2. 服务器端兜底处理（可选） #

如果Swagger UI的配置无法完全避免空数组发送，你可以在Hapi路由的options里开启validate.options.stripUnknown，让服务器自动移除请求体中未定义或可选但为空的字段：

server.route({
  method: 'POST',
  path: '/addCompany',
  options: {
    validate: {
      payload: yourJoiSchema,
      options: {
        stripUnknown: true, // 移除Schema中未定义的字段
        abortEarly: false
      }
    },
    plugins: {
      'hapi-swagger': { /* 你的swagger配置 */ }
    }
  },
  handler: (request, h) => { /* 处理逻辑 */ }
});

这个方法作为服务器端兜底，确保即使前端发送了空数组，服务器也会自动剔除它们。

3. GET查询参数的同类问题解决 #

对于GET请求的查询参数，同样可以用类似的Joi配置：给可选参数添加allow(null)和meta({ swagger: { nullable: true } })，确保hapi-swagger生成的Swagger定义里这些参数的required为false且nullable为true。示例如下：

// GET查询参数的Joi Schema
Joi.object().keys({
  name: Joi.string().required(),
  idsUser: Joi.array().items(Joi.string())
    .optional()
    .allow(null)
    .meta({ swagger: { nullable: true } }),
  idsUsergroup: Joi.array().items(Joi.string())
    .optional()
    .allow(null)
    .meta({ swagger: { nullable: true } })
});

这样Swagger UI的查询参数输入框就不会自动填充空值，只会保留必填参数。

关键原理 #

Swagger UI的jsonEditor默认会根据Swagger定义里的properties自动填充所有字段的默认值（数组默认是空数组），只有当字段被标记为nullable: true时，它才会允许字段不存在，不会强制填充空值。而hapi-swagger需要通过Joi的meta方法来生成这个nullable标记，因为默认情况下Joi的可选字段不会自动触发该标记。

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