如何在Newman生成的HTML报告中展示查询参数及适配SwaggerUI

1. 如何在Newman生成的报告中展示查询参数、实现类Swagger展示效果 #

你用的newman-reporter-htmlextra默认模板没有做query参数的渲染逻辑，不是工具拿不到参数数据，有三个可直接落地的方案：

• 自定义htmlextra报告模板
  newman-reporter-htmlextra基于Handlebars模板引擎渲染，支持自定义模板覆盖默认逻辑：
  1. 找到本地npm安装目录下newman-reporter-htmlextra包内的默认template.hbs文件，复制到你的项目工作目录
  2. 定位到模板中渲染请求URL的代码块，新增遍历request.url.query数组的逻辑，过滤掉disabled: true的未启用参数，按Swagger风格的参数表格格式渲染参数名、示例值、字段描述即可
  3. 运行Newman命令时追加参数--reporter-htmlextra-template ./你的自定义模板路径.hbs，就能生成带query参数展示的报告
• 替换为自带结构化参数展示的报告器
  直接更换成newman-reporter-swagger这类面向接口文档场景的报告器，这类报告器默认就会把query参数、path参数、请求体、响应字段按接口文档的结构化形式输出，不需要手动修改模板，生成的效果和你预期的Swagger风格基本一致。
• 运行时动态注入参数内容
  如果不想改模板也不想换报告器，可以写一段Node脚本调用Newman，绑定beforeRequest事件把当前请求的query参数格式化成Markdown表格，追加到请求描述字段中——newman-reporter-htmlextra默认会完整渲染请求描述内容，也能实现参数展示的效果，核心参考代码：

  const newman = require('newman');
  newman.run({
    collection: './你的postman_collection文件路径.json',
    reporters: ['htmlextra']
  }).on('beforeRequest', (err, data) => {
    const queryList = data.request.url.query || [];
    let querySection = '\n### Query参数列表\n| 参数名 | 参数值 | 描述 |\n| ---- | ---- | ---- |\n';
    queryList.filter(item => !item.disabled).forEach(item => {
      querySection += `| ${item.key} | ${item.value || ''} | ${item.description || ''} |\n`;
    });
    data.request.description = (data.request.description || '') + querySection;
  });
  

2. 是否支持Postman Collection v2.1转Swagger UI的报告器 #

目前Newman生态里没有专门的、直接生成Swagger UI页面的原生报告器，但有成熟的方案可以零成本打通这个流程：

• 先使用postman-to-openapi这类转换工具，它完全兼容Postman Collection v2.1格式，可以直接把collection文件转换成标准的Swagger 2.0/OpenAPI 3.0规范文件，自动识别query参数、path参数、请求体结构、响应示例，转换准确率很高。
• 如果需要和Newman测试流程绑定，可以在Newman运行的done事件钩子里调用上述转换工具，测试执行完成后自动生成OpenAPI规范文件，再通过http-server之类的静态服务挂载Swagger UI静态页、加载生成的规范文件，就能实现测试跑完自动生成可访问的Swagger文档的效果，和专用报告器的体验没有区别。

小提示：转换前尽量补全Postman collection里的参数描述、响应示例，转换生成的Swagger文档完整度会高很多，基本不需要二次调整。

内容的提问来源于stack exchange，提问作者Mr. Hobo