引言
我们平时开发一般都用postman
来做简单开发,写好接口,放postman
里一测就完事了,后续写文档是个超级痛苦的事情,一点都不想干
所以搞了个postman
收藏导出成json
文件,然后用js
来做一些解析处理,生成一个markdown
文档,这样看的也方便
效果
脚本源码
此脚本因为是我在本地运行的,就基本上使用了模板字符串拼接,没有使用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.');
}
});
});