Postman API文档生成的自定义格式与同步更新方案

在日常开发里，接口文档就像团队之间的“传话员”。后端改了接口，前端还不知道，等到联调时才发现对不上，于是互相甩锅、加班改错。Postman 本来只是用来调试接口的工具，但很多人没注意到，它其实能生成一份看得过去、甚至能自动更新的 API 文档。更妙的是，我们能把这份文档转成自己想要的格式，比如 Markdown、HTML，或者推到内部 Wiki 上。这篇文章就把这套玩法掰开揉碎讲清楚，全程不绕弯子，用最直白的话和能直接跑的代码，带你把“文档生成+自动同步”这条链路搭起来。

一、先把场景讲明白

1.1 为什么需要自定义格式

Postman 自带的文档页面，样子挺好看，但有个问题：它是 Postman 官方网页，要么公网访问，要么通过团队订阅。很多公司内网环境根本不允许把接口信息传到外部，这时候就需要把文档导出来，转成内部能放行的格式。

还有一个更常见的场景：公司内部用 GitLab 或 Wiki 管文档，文档格式通常是 Markdown。Postman 默认的导出格式是 JSON，没法直接贴到 Wiki 上。这时咱们可以写一段脚本，读 Postman 导出的 JSON，然后生成自己想要的 Markdown 文件，再通过 Git 或 API 推上去。整个过程可以做到全自动，接口一改，文档跟着改。

1.2 同步更新如何实现

同步更新的核心思路其实很简单：Postman 提供一个 Collection JSON 文件，里面包含了接口的 URL、方法、请求头、请求体、描述等信息。我们可以通过 Postman API 拿到这个 JSON，也可以在 Postman 里手动导出。拿到 JSON 后，写个脚本解析它，再生成目标格式的文档，最后用自动化工具（比如 GitHub Actions、Jenkins、Windows 计划任务）定时执行。这个流程一旦跑起来，文档永远跟着代码走。

二、技术选型和准备工作

2.1 选什么技术栈

这篇文章统一用 Node.js 做示例，理由很简单：JavaScript 生态里处理 JSON 非常顺手，而且 Node.js 几乎是每台开发机的标配。你不用装额外的东西，只要有一个 Node.js 环境就行。

2.2 需要准备哪些材料

第一，一个 Postman 集合。不懂什么是集合？就是你在 Postman 左边栏创建的文件夹，里面存着很多请求。在 Postman 主界面选中一个集合，点右键，选择“导出”，就能得到一个 JSON 文件。
第二，Node.js 环境。到官网下载安装即可，装完后在终端里执行 node -v，能输出版本号就说明没事。
第三，一个存放脚本的文件夹，例如 doc-generator。
第四，可选：如果你想把文档同步到 GitLab，需要 GitLab 的 Token；如果是同步到本地，那就啥都不用。

2.3 Postman 导出的 JSON 长什么样

我们先看一眼结构，这样后面解析的时候心里有底。以下是一个典型的 Postman Collection v2.1 格式：

{
  "info": {
    "name": "用户服务",
    "description": "这是用户相关的接口集合"
  },
  "item": [
    {
      "name": "获取用户信息",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{token}}"
          }
        ],
        "url": {
          "raw": "https://api.example.com/users/123",
          "host": ["api.example.com"],
          "path": ["users", "123"]
        },
        "description": "根据用户ID返回用户详情"
      },
      "response": []
    }
  ]
}

看到了吧，这个 JSON 里有接口名、请求方法、地址、请求头、说明。这就是我们能拿到的“原始素材”。

三、自定义格式生成器

3.1 搭一个基础项目

在文件夹里初始化一个 Node.js 项目，然后安装一个用起来像喝水一样简单的依赖——fs 是自带的，不需要装。我们只需要自己写核心代码。

# 创建项目目录
mkdir doc-generator

# 进入目录
cd doc-generator

# 初始化 package.json，全部用默认值
npm init -y

我们不需要第三方库，只用 Node.js 自带模块，这样你拿到代码就能跑。

3.2 读取 Postman 导出的 JSON

假设你导出的文件叫 collection.json，放在 doc-generator 目录下面。我们写一个入口文件 generate.js。技术栈标注为 Node.js（JavaScript）。

// 使用 Node.js 内置的 fs 模块，用来读写文件
const fs = require('fs');

// 同步读取 Postman 导出的 JSON 文件，并转为对象
// 这一步相当于把 Postman 的数据“拿”到我们手里
const collection = JSON.parse(fs.readFileSync('collection.json', 'utf-8'));

// 打印集合名称，确认读取成功
console.log('读取到的集合名称：', collection.info.name);

3.3 把接口数组抽取出来

Postman 的集合结构是嵌套的，item 可能一层，也可能多层（比如文件夹套文件夹）。我们写一个递归函数，把所有接口请求都“拍平”成一个列表，这样后续生成文档时就方便遍历了。

// 定义接口数组，稍后会把所有请求塞进去
let requests = [];

// 这个函数用来递归遍历 item
// 如果某个 item 里面还有 item，就继续往里走
// 如果某个 item 里面是 request，说明它是一个接口，存起来
function walkItems(items) {
  items.forEach((item) => {
    if (item.request) {
      // 有 request 字段，说明是一个真正的接口
      requests.push({
        name: item.name,           // 接口名称
        method: item.request.method, // 请求方法，比如 GET、POST
        url: item.request.url.raw, // 完整的请求地址
        description: item.request.description || '', // 接口描述
        headers: item.request.header || [] // 请求头，可能为空数组
      });
    }
    if (item.item) {
      // 如果还有子 item，递归处理
      walkItems(item.item);
    }
  });
}

// 调用递归函数，从集合的 item 开始遍历
walkItems(collection.item);

// 打印出第一层接口数量
console.log('共找到接口数量：', requests.length);

3.4 生成 Markdown 文档

接下来是核心部分：把我们拿到的接口列表生成一份排版整齐的 Markdown 文档。Markdown 是一种轻量级标记语言，写起来简单，GitLab、GitHub、Confluence 都认它。

我们设计一下文档结构：

• 顶部是集合名称和描述
• 每个接口用二级标题 ## 分隔
• 接口下面列出方法、地址、请求头、接口说明
• 如果以后有请求体，也可以扩展现有代码

这里给出完整代码：

// 引入 fs 模块（再次用到）
const fs = require('fs');

// ========== 递归提取接口 ==========
let requests = [];
function walkItems(items) {
  items.forEach((item) => {
    if (item.request) {
      requests.push({
        name: item.name,
        method: item.request.method,
        url: item.request.url.raw,
        description: item.request.description || '',
        headers: item.request.header || []
      });
    }
    if (item.item) {
      walkItems(item.item);
    }
  });
}

// ========== 生成 Markdown ==========
function buildMarkdown(collection, reqList) {
  // 先拼上集合头部信息
  let lines = [];

  // 一级标题，表示这是文档大标题
  lines.push(`# ${collection.info.name}`);
  lines.push('');

  // 集合描述如果有，就展示出来
  if (collection.info.description) {
    lines.push(collection.info.description);
    lines.push('');
  }

  // 遍历每个接口，生成文档主体
  reqList.forEach((req, index) => {
    // 用序号加接口名作为二级标题
    lines.push(`## ${index + 1}. ${req.name}`);
    lines.push('');

    // 请求方法 + 地址
    lines.push(`- **请求方法**：\`${req.method}\``);
    lines.push(`- **请求地址**：\`${req.url}\``);
    lines.push('');

    // 描述
    if (req.description) {
      lines.push(`**接口说明**：${req.description}`);
      lines.push('');
    }

    // 请求头，可能有多个
    if (req.headers.length > 0) {
      lines.push('**请求头**：');
      lines.push('');
      lines.push('| 参数名 | 参数值 |');
      lines.push('| --- | --- |');
      req.headers.forEach((header) => {
        // 转义表格中的竖线，避免破坏表格结构
        const key = (header.key || '').replace(/\|/g, '\\|');
        const value = (header.value || '').replace(/\|/g, '\\|');
        lines.push(`| ${key} | ${value} |`);
      });
      lines.push('');
    }

    // 为了让文档不显得太挤，接口之间加一个分隔线
    lines.push('---');
    lines.push('');
  });

  return lines.join('\n');
}

// ========== 主流程 ==========
// 读取 Postman 导出的 JSON 文件
const collection = JSON.parse(fs.readFileSync('collection.json', 'utf-8'));

// 遍历提取接口
walkItems(collection.item);

// 生成 Markdown 文本
const markdownText = buildMarkdown(collection, requests);

// 写入 output.md 文件
fs.writeFileSync('output.md', markdownText, 'utf-8');

// 控制台提示用户
console.log('文档已生成：output.md');

3.5 运行脚本

在终端里执行以下命令：

# 用 Node 运行生成脚本
node generate.js

执行完后，你会在当前文件夹里看到一个 output.md，打开就是一份格式干净、包含所有接口信息的文档。如果你需要把它转成 PDF，可以借助 VS Code 的 Markdown 插件或者 Typora。

四、关联技术：Postman API 与自动化唤醒

4.1 从 Postman 云端拉取最新集合

上面的示例是手动导出 JSON。但如果接口改得很频繁，每次手动导出还是麻烦。Postman 官方提供了一套 API，只要你有 Postman 账号的 API Key，就能在浏览器或脚本里直接拉取集合数据。这样我们就能实现“一键同步”，根本不用打开 Postman。

获取 API Key 的方法：登录 Postman 网页版，前往 postman.com/settings，找到 API Keys，生成一个。把 Key 放在环境变量里，别写死在代码中。

获取集合所有信息的 API 长这样：

GET https://api.getpostman.com/collections?apikey=你的Key

你还需要知道 collectionUid，通过上面这个接口能拿到。然后用下面的接口拉取单个集合详情：

GET https://api.getpostman.com/collections/{collectionUid}?apikey=你的Key

我们可以写一个简单的 Node.js 脚本，把集合拉下来并保存成 collection.json，再接上刚才生成 Markdown 的代码，一条龙完成。

// 使用 Node.js 内置的 https 模块发起网络请求
const https = require('https');
const fs = require('fs');

// 从环境变量读取 API Key，避免泄漏
const API_KEY = process.env.POSTMAN_API_KEY;

// 替换成你的集合 UID
const COLLECTION_UID = '1234567-abcdef';

// 拼接请求地址
const url = `https://api.getpostman.com/collections/${COLLECTION_UID}?apikey=${API_KEY}`;

// 发起 GET 请求
https.get(url, (res) => {
  let data = '';

  // 不断接收数据块
  res.on('data', (chunk) => {
    data += chunk;
  });

  // 接收完毕后处理
  res.on('end', () => {
    // 把响应内容解析成 JSON
    const json = JSON.parse(data);

    // Postman API 返回的数据结构里，集合本体在 collection 字段下
    const collection = json.collection;

    // 保存成 collection.json，备用
    fs.writeFileSync('collection.json', JSON.stringify(collection, null, 2), 'utf-8');

    console.log('已拉取最新集合并保存到 collection.json');
  });
}).on('error', (err) => {
  // 如果网络出错，打印错误信息
  console.error('拉取集合失败：', err.message);
});

将上面的代码保存为 download.js，然后在终端运行：

# 在 Windows PowerShell 中设置环境变量
$env:POSTMAN_API_KEY = "你的Key"

# 在 macOS / Linux 中设置环境变量
export POSTMAN_API_KEY="你的Key"

# 运行下载脚本
node download.js

# 运行生成脚本
node generate.js

这样，我们就把手动操作变成了两行命令。如果想要更省事，还可以把这两行命令写进一个 run.sh（macOS/Linux）或 run.bat（Windows）里。

4.2 自动同步到 GitLab 或 Wiki

文档生成出来之后，下一步是让文档自动出现在团队能看到的地方。最常见的是推到 GitLab 的文档仓库。我们可以用 Git 命令行操作，也可以直接用 GitLab API 创建或更新文件。

假设我们最终文件叫 output.md，GitLab 仓库地址是 https://gitlab.com/team/doc.git，那么同步步骤如下：

# 拉取最新仓库代码
git clone https://gitlab.com/team/doc.git docs-repo

# 把生成的文档复制到仓库里
cp output.md docs-repo/api.md

# 进入仓库目录
cd docs-repo

# 添加到暂存区
git add api.md

# 提交，留言注明更新时间
git commit -m "更新API文档"

# 推送到远程仓库（注意替换分支名）
git push origin main

如果公司内部不允许用 Git 命令行，我们也可以直接用 GitLab 的 Project API 上传文件，不过需要 Token。这个流程相对复杂，但核心思路是一样的：先准备好文件内容，再调用 API 写入。

4.3 使用定时任务让同步自动跑

手动跑脚本还是不够“自动化”。我们可以在电脑或服务器上设置定时任务，让脚本每天凌晨自动执行一次。这样，哪怕不打开电脑，文档也会悄悄更新。

在 Linux 上使用 crontab 命令：

# 每天凌晨 2 点执行，先下载，再生成，最后推送到 Git
0 2 * * * cd /path/to/doc-generator && node download.js && node generate.js && bash push.sh

在 Windows 上可以使用“任务计划程序”，配置触发器为“每天”，操作设置为执行 run.bat。这种方式非常适合小团队或者个人项目。

五、应用场景与优缺点

5.1 适合用在哪

这个方案最适合下面几类人：

• 前后端开发人员：后端写完接口，在 Postman 里调试好，导出一份 JSON，前端拿到 Markdown 文档，直接对着开发，不用再问来问去。
• 测试人员：测试用例需要接口参数说明，文档生成后可以直接贴到测试用例里，形成知识库。
• 小团队内部协作：没有钱买专业的 API 管理平台，用 Postman 加脚本就够用。
• 接口经常变化的项目：每周发版本，接口改了又改，手动维护文档肯定跟不上，用定时任务最稳妥。

5.2 技术优点

第一，零成本。Postman 免费版就支持导出，Node.js 也是免费开源，整个链路不用掏一分钱。
第二，可定制性高。你可以完全控制文档的排版，想输出什么结构就输出什么结构，比如增加请求参数表格、响应示例等等。
第三，降低沟通成本。文档生成后，前端、测试、后端看同一份资料，不容易产生理解偏差。
第四，全程可审计。脚本每次生成的文档都会带上时间戳，哪一天改了什么东西，一目了然。

5.3 技术缺点

第一，依赖 Postman 的使用习惯。如果后端开发不习惯在 Postman 里写描述信息，生成的文档就会缺胳膊少腿。
第二，缺少交互式调试功能。生成的 Markdown 是静态的，不能像 Postman 网页那样可以点按钮发请求。
第三，对于嵌套特别深的集合，递归脚本需要仔细测试，否则可能漏掉某些接口。
第四，Postman API 有频率限制，如果你频繁拉取，可能被临时封禁。

六、注意事项

6.1 接口描述别偷懒

在 Postman 里，每个请求都能填 description 字段。很多人反应描述是属于“可填可不填”的东西，其实这直接决定生成文档的质量。建议在团队内部约定：接口必须有描述，哪怕只写一句话“获取用户信息”。

6.2 安全信息千万别进文档

Postman 集合里如果带有 Authorization 头，而且值是真实 Token，那么导出生成的文档也会带上这些敏感信息。建议把请求头里的敏感变量统一写成占位符，比如 {{token}}、{{secret}}，在生成文档时保留占位符即可，不要替换成真实值。

6.3 注意集合的数据结构

Postman 的 Collection JSON 有两种版本，v2.0 和 v2.1。两种版本的字段有些许差异，比如 v2.1 的 url.raw 可能没有，而 url 是一个对象。你可以在脚本里做一段兼容判断，确保两种格式都能生成。

// 兼容 v2.1 中可能缺失 raw 字段的情况
let rawUrl = '';
if (req.url.raw) {
  rawUrl = req.url.raw;
} else {
  // 如果没有 raw，就手动拼接 host 和 path
  rawUrl = req.url.host.join('.') + '/' + req.url.path.join('/');
}

6.4 同步时记得保留历史记录

如果直接覆盖 Git 仓库里的 api.md，别人就看不到之前的版本了。建议每次提交后加一个带日期的分支，或者利用 Git 自带的版本记录，这样万一文档出错，可以随时回滚。

6.5 定时任务别设太频繁

接口不是每秒都在变，每天同步一次已经非常充足。如果不是上线期，可以调成每周一次，减少对 Postman API 的消耗。

七、文章总结

Postman 生成 API 文档这件事，看起来只是一个小小的“导出功能”，但配合上一段 Node.js 脚本，就能变成一套完整的内容流水线。我们从手写的 JSON 到生成 Markdown，从手动点击到定时任务，每一步都不复杂，但组合在一起威力很大。核心流程就五步：用 Postman 管理接口 → 导出或拉取 Collection JSON → 用脚本解析 → 生成自定义格式文档 → 自动推送并定时更新。关键是让接口信息只维护一份（Postman 里），所有下游文档都从这一份数据里派生。这样做，不仅省去了人工写文档的枯燥时间，还消除了信息不同步的隐患。如果你正在被接口文档折磨，不妨照着这篇文章搭一套试试，相信你会回来感谢这个方案的。

希望这篇文章能给你一些启发，让你在工具与自动化之间找到更好的平衡点。真正的效率提升，往往就藏在这样一条不起眼的小脚本里。