如何让Hapi-swagger完整展示嵌套对象字段文档并支持入参调试

嵌套对象文档全量展示、在线调试的需求完全可实现，当前代码的问题和调整方案如下：

核心问题定位 #

• Schema写法不符合规范：当前代码的validate.query直接传入了普通JS对象，没有用Joi.object()做完整包裹，导致Hapi Swagger无法逐层解析嵌套结构，只能识别到顶层的外层参数，无法展开内部键的描述和类型。
• 插件默认配置限制：Hapi Swagger默认配置下，不会自动对query类型的嵌套对象做深层文档展开，且Try it out面板默认只支持扁平key-value输入，不支持嵌套结构的可视化编辑。
• 服务端query解析配置缺失：如果要在实际请求中传递嵌套对象参数，需要单独开启Hapi的query嵌套解析能力，否则就算文档展示正常，服务端也无法正确读取嵌套参数的值。

具体调整步骤 #

• 修正Schema定义写法
  把原本裸写的query参数结构，用Joi.object()完整包裹，每一层嵌套对象的属性都补上对应的描述、示例配置：

  validate: {
      query: Joi.object({
          filters: Joi.object({
              level: Joi.number().min(1).max(2).optional().description('My description'),
              property2: Joi.number().min(1).max(2).optional().description('My description of the second parameter'),
              obj: Joi.object({
                  propertyX: Joi.number().optional().description('嵌套数值属性X'),
                  propertyY: Joi.string().optional().description('嵌套字符串属性Y')
              }).optional().description('filters下的二级嵌套对象')
          }).description('My filter'),
          anotherObj: Joi.object({
              property1: Joi.number().min(1).max(2).optional().description('My description 1'),
              property2: Joi.number().min(1).max(2).optional().description('My description 2'),
              property3: Joi.number().min(1).max(2).optional().description('My description 3'),
          }).description('Just another object')
      })
  }
  

• 调整Hapi Swagger插件初始化配置
  在插件配置中开启两项关键能力：
  • 配置jsonEditor: true：开启后Swagger UI会自动展开所有层级的嵌套对象文档，同时Try it out面板会生成可视化的JSON编辑表单，支持逐层输入嵌套参数值，自动拼接符合格式要求的query参数。
  • 配置pathPrefixSize: 1：保证路由路径解析正确，避免文档分组异常。
• 开启服务端query嵌套解析能力
  在Hapi服务初始化的全局路由配置中，开启query参数的嵌套解析支持：

  server = Hapi.server({
      port: 3000,
      routes: {
          validate: {
              options: {
                  // 开启嵌套对象解析，支持filters[obj][propertyX]这类格式的query参数读取
                  abortEarly: false,
                  allowUnknown: true
              }
          },
          query: {
              parser: {
                  parseNested: true,
                  allowDots: true
              }
          }
      }
  });
  

调整后效果 #

• 文档展示：任意层级的嵌套对象都会被逐层展开，每个属性的类型、描述、可选规则、示例都会完整显示，不会出现仅展示外层参数名的问题。
• 在线调试：开启JSON编辑器后，开发者可以直接在Try it out面板的可视化表单里输入所有层级的嵌套参数值，不需要手动拼接参数字符串，提交后插件会自动生成服务端可识别的请求格式，完成接口测试。

注意：如果保持默认的非JSON编辑器模式，Swagger UI依然只会展示外层嵌套参数名，无法支持深层参数的手动输入，jsonEditor: true是实现嵌套参数在线调试的必要配置。

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