引言

我们平时开发一般都用postman来做简单开发,写好接口,放postman里一测就完事了,后续写文档是个超级痛苦的事情,一点都不想干

所以搞了个postman收藏导出成json文件,然后用js来做一些解析处理,生成一个markdown文档,这样看的也方便

效果

生成结果(typora软件预览)

生成文件

脚本源码

此脚本因为是我在本地运行的,就基本上使用了模板字符串拼接,没有使用document对象来做

const fs = require('fs');

// 读取Postman Collection JSON文件
fs.readFile('postman_collection.json', 'utf-8', (err, data) => {
  if (err) {
    console.error('Error reading file:', err);
    return;
  }

  // 解析JSON数据
  const collection = JSON.parse(data);

  // 创建Markdown文档
  let markdown = '';

  function getCodeBox(obj, type = 'json') {
      return `\n\n\`\`\`${type}\n${JSON.stringify(obj, null, 2)}\n\`\`\`\n\n`
  }

  // 递归遍历请求项和文件夹
  function traverseItems(items, depth = 1) {
    items.forEach(item => {
      if (item.item) {
        // console.log(depth+1, item.name);
        // 如果有子项,则递归处理子文件夹
        markdown += `\n${'#'.repeat(depth + 1)} ${item.name}\n\n`;
        traverseItems(item.item, depth + 1);
      } else {
        // 处理单个请求项
        let authInfo = '';
        if (item.auth) {
          authInfo = `**Authentication**\n\`${JSON.stringify(item.auth, null, 2)}\``;
        }

        let variables = '';
        if (item.variable) {
          variables = `**Variables**\n\`${JSON.stringify(item.variable, null, 2)}\``;
        }

        let prerequestScript = '';
        if (item.event && item.event.some(e => e.listen === 'prerequest')) {
          prerequestScript = `- **请求拦截**: ${getCodeBox(item.event.filter(e => e.listen === 'prerequest')[0].script.exec.join('\n'))}\n`;
        }

        let testScript = '';
        if (item.event && item.event.some(e => e.listen === 'test')) {
            let testStr = item.event.filter(e => e.listen === 'test')[0].script.exec.join('\n')
            testScript = `- **响应拦截** \n\`\`\`js\n${testStr}\n\`\`\`\n`;
        }

        // 接口名称
        markdown += `\n${'#'.repeat(depth + 1)} ${item.name}\n\n`;
        // 接口地址
        markdown += `- **接口地址:** ${item.request.url.raw}\n\n`;
        markdown += `- **请求类型:** ${item.request.method}\n\n`;
        markdown += `- **请求头部:** ${getCodeBox(item.request.header)}\n`;
        if (item.request.body) {
            markdown += `- **加密方式:** ${item.request.body.mode}\n`;
            markdown += `- **请求参数:** ${getCodeBox(item.request.body.urlencoded)}\n`;
        } else {
            markdown += `- **请求参数:** ${getCodeBox(item.request.body)}\n`;
        }

        if (authInfo) markdown += `\n${authInfo}\n`
        if (authInfo) markdown += `\n${variables}\n`
        if (authInfo) markdown += `\n${prerequestScript}\n`
        if (authInfo) markdown += `\n${testScript}\n`
      }
    });
  }

  // 开始递归遍历
  traverseItems(collection.item);

  // 添加全局变量和环境
  if (collection.variable) {
    markdown += `\n## Global Variables\n ${getCodeBox(collection.variable)}`;
  }

  if (collection.auth) {
    markdown += `
      \n## Global Authentication\n
      \`${JSON.stringify(collection.auth, null, 2)}\`
    `;
  }

  // 写入Markdown文件
  fs.writeFile('api_docs.md', markdown, err => {
    if (err) {
      console.error('Error writing file:', err);
    } else {
      console.log('API documentation has been generated successfully.');
    }
  });
});

欢迎关注拓行公众号,分享各种技术博客文章

拓行——奋勇进取,开拓未来,砥砺前行

最后修改:2024 年 07 月 25 日
如果您对各种技术博客文章感兴趣,欢迎关注拓行公众号,分享各种专业技术知识~