pull-apifox 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# pull-apifox
+
+从 [Apifox](https://apifox.com) 拉取接口，按需筛选，自动生成带完整 JSDoc 的 JS 请求函数。
+
+## 安装
+
+```bash
+npm install -g pull-apifox
+```
+
+## 快速开始
+
+### 1. 在项目根目录创建 `apifox.config.json`
+
+```json
+{
+  "projectId": "1577893",
+  "accessToken": "aps-xxxxxxxxxx",
+  "output": "./src/apifox",
+  "showReturns": true,
+  "importPath": "@/utils/request",
+
+  "pull": [
+    { "tags": ["移库单管理"], "name": "womeiTransfer", "prefix": "/chainova/womei" }
+  ]
+}
+```
+
+### 2. 运行
+
+```bash
+pull-apifox
+# 或指定配置文件
+pull-apifox ./path/to/apifox.config.json
+```
+
+## 配置项
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `projectId` | string | **必填** | Apifox 项目 ID |
+| `accessToken` | string | — | Apifox 令牌，填了走云端 API |
+| `localPort` | number | `4523` | 本地客户端端口 |
+| `output` | string | `./src/apifox` | 输出目录 |
+| `showReturns` | boolean | `false` | 是否生成返回值 JSDoc |
+| `importPath` | string | `@/utils/request` | request 导入路径 |
+| `pull` | array | **必填** | 拉取任务列表 |
+
+### pull 配置
+
+每项生成一个 JS 文件，三个筛选维度**取交集**：
+
+```json
+{
+  "tags": ["移库单管理"],        // Apifox 文件夹名，支持层级模糊匹配
+  "folder": "/movement-orders",  // URL 路径前缀匹配
+  "apis": ["login", "order"],    // 接口名关键词
+  "name": "womeiTransfer",       // 生成文件名
+  "prefix": "/chainova/womei"    // 请求路径前缀
+}
+```
+
+> `tags` 对应 Apifox 文件夹层级路径（如 `沃美/移库单管理`），配 `"移库单管理"` 即可匹配。
+
+## 获取 Token
+
+Apifox 网页 → 头像 → 账号设置 → 访问令牌 → 新建令牌。
+
+## 生成结果
+
+```
+src/apifox/
+├── index.js            # 入口文件，聚合导出
+└── api/
+    └── womeiTransfer.js  # 接口函数，带 JSDoc
+```
+
+### 生成代码示例
+
+```js
+import request from '@/utils/request';
+
+/**
+ * 新建移库单
+ *
+ * POST /movement-orders/create
+ * @param {object} data - 请求体
+ * @param {string} data.ownerCorpCode - 货主企业编码
+ * @param {string} data.warehouseCode - 仓库编码
+ * @param {string} [data.remark] - 备注
+ * @param {object[]} data.items - 移库单项列表
+ * @param {string} data.items[].skuCode - SKU编码
+ * @param {number} data.items[].quantity - 数量
+ * @returns {Promise<object>} - 响应数据
+ * @param {number} returns.code - 状态码
+ * @param {string} returns.msg - 消息
+ */
+export function createMovementOrder(data) {
+  return request({
+    url: '/chainova/womei/movement-orders/create',
+    method: 'POST',
+    data,
+  });
+}
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+const { main } = require('../lib');
+main().catch(err => {
+  console.error('\n❌', err.message);
+  process.exit(1);
+});

package/lib/index.js

@@ -0,0 +1,478 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const http = require('http');
+
+// ======================== HTTP 请求 ========================
+
+function request(url, options = {}) {
+  return new Promise((resolve, reject) => {
+    const isHttps = url.startsWith('https://');
+    const lib = isHttps ? https : http;
+    const urlObj = new URL(url);
+
+    const req = lib.request({
+      hostname: urlObj.hostname,
+      port: urlObj.port || (isHttps ? 443 : 80),
+      path: urlObj.pathname + urlObj.search,
+      method: options.method || 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'pull-apifox/1.0',
+        ...options.headers,
+      },
+      rejectUnauthorized: false,
+    }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try { resolve(JSON.parse(body)); } catch { resolve(body); }
+        } else {
+          let msg = `HTTP ${res.statusCode}`;
+          try {
+            const errBody = JSON.parse(body);
+            msg = errBody.message || errBody.msg || JSON.stringify(errBody);
+          } catch {}
+          reject(new Error(msg));
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(30000, () => { req.destroy(); reject(new Error('请求超时')); });
+    if (options.body) req.write(JSON.stringify(options.body));
+    req.end();
+  });
+}
+
+// ======================== 拉取 OpenAPI 规范 ========================
+
+async function fetchSpec(projectId, scope, config) {
+  const token = config.accessToken;
+
+  if (token) {
+    const url = `https://api.apifox.com/api/v1/projects/${projectId}/export-openapi`;
+    console.log(`   📡 云端 API: ${projectId}`);
+    const body = scope
+      ? { exportFormat: 'OpenAPI3.0', scope }
+      : { exportFormat: 'OpenAPI3.0' };
+
+    return request(url, {
+      method: 'POST',
+      body,
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'X-Apifox-Api-Version': '2024-03-28',
+      },
+    });
+  } else {
+    const port = config.localPort || 4523;
+    const url = `http://127.0.0.1:${port}/export/openapi/${projectId}?version=3.0`;
+    console.log(`   📡 本地客户端: ${url}`);
+
+    try {
+      return await request(url, {
+        method: 'POST',
+        body: scope ? { exportFormat: 'OpenAPI3.0', scope } : { exportFormat: 'OpenAPI3.0' },
+      });
+    } catch {
+      return request(url);
+    }
+  }
+}
+
+// ======================== 筛选引擎 ========================
+
+function matchApiName(operation, route, keyword) {
+  const kw = keyword.toLowerCase();
+
+  if (operation.operationId && operation.operationId.toLowerCase().includes(kw)) return true;
+  if (operation.summary && operation.summary.toLowerCase().includes(kw)) return true;
+
+  const lastSegment = route.split('/').pop().toLowerCase();
+  if (lastSegment.includes(kw)) return true;
+  if (route.toLowerCase().includes(kw)) return true;
+
+  return false;
+}
+
+function matchTags(operation, tags) {
+  if (!tags || tags.length === 0) return true;
+  const opTags = (operation.tags || []).map(t => t.toLowerCase());
+  return tags.some(t => {
+    const kw = t.toLowerCase();
+    return opTags.some(ot => ot === kw || ot.endsWith('/' + kw) || ot.includes('/' + kw + '/'));
+  });
+}
+
+function matchFolder(route, folder) {
+  if (!folder) return true;
+  const normalizedRoute = route.startsWith('/') ? route : `/${route}`;
+  const normalizedFolder = folder.startsWith('/') ? folder : `/${folder}`;
+  return normalizedRoute === normalizedFolder || normalizedRoute.startsWith(normalizedFolder + '/');
+}
+
+function matchAll(route, methodObj, operation, filters) {
+  if (filters.folder && !matchFolder(route, filters.folder)) return false;
+  if (filters.tags && filters.tags.length > 0 && !matchTags(operation, filters.tags)) return false;
+  if (filters.apis && filters.apis.length > 0) {
+    if (!filters.apis.some(kw => matchApiName(operation, route, kw))) return false;
+  }
+  return true;
+}
+
+function filterSpec(spec, filters) {
+  const result = JSON.parse(JSON.stringify(spec));
+  const allCount = Object.keys(result.paths || {}).length;
+
+  for (const [route, methods] of Object.entries(result.paths || {})) {
+    if (!methods || typeof methods !== 'object') continue;
+    let keepRoute = false;
+
+    for (const [method, operation] of Object.entries(methods)) {
+      if (!operation || typeof operation !== 'object') continue;
+      if (matchAll(route, method, operation, filters)) {
+        keepRoute = true;
+      } else {
+        delete methods[method];
+      }
+    }
+
+    if (!keepRoute) {
+      delete result.paths[route];
+    } else {
+      const remaining = Object.values(methods).filter(v => v && typeof v === 'object');
+      if (remaining.length === 0) delete result.paths[route];
+    }
+  }
+
+  const keptCount = Object.keys(result.paths).length;
+  console.log(`   🔍 ${allCount} → ${keptCount} 个接口`);
+  return result;
+}
+
+// ======================== JS 代码生成 ========================
+
+function isAscii(str) {
+  if (!str) return false;
+  return /^[\x00-\x7F]+$/.test(str);
+}
+
+function deriveModuleName(apis) {
+  for (const api of apis) {
+    const seg = api.route.split('/').filter(Boolean)[0];
+    if (seg && /^[a-zA-Z]/.test(seg)) return seg;
+  }
+  return 'api';
+}
+
+function toCamel(str) {
+  return str
+    .replace(/[^a-zA-Z0-9_]/g, '_')
+    .replace(/_+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/^[A-Z]/, c => c.toLowerCase());
+}
+
+function toFuncName(operation, method, route) {
+  if (operation.operationId) return toCamel(operation.operationId);
+  if (isAscii(operation.summary)) return toCamel(operation.summary);
+  return toCamel(`${method}_${route.replace(/[\/{}]/g, '_')}`);
+}
+
+function resolveRef(schema, fullSpec) {
+  if (!schema) return schema;
+  if (schema.$ref) {
+    const p = schema.$ref.replace('#/', '').split('/');
+    let obj = fullSpec;
+    for (const seg of p) obj = obj?.[seg];
+    return obj || schema;
+  }
+  return schema;
+}
+
+function toJSDocType(schema, fullSpec) {
+  const resolved = resolveRef(schema, fullSpec);
+  if (!resolved || !resolved.type) return 'any';
+  switch (resolved.type) {
+    case 'string': return 'string';
+    case 'integer':
+    case 'number': return 'number';
+    case 'boolean': return 'boolean';
+    case 'array': {
+      const itemType = toJSDocType(resolved.items, fullSpec);
+      return itemType === 'any' ? 'any[]' : `${itemType}[]`;
+    }
+    case 'object': return 'object';
+    default: return 'any';
+  }
+}
+
+function buildJSDoc(operation, method, route, funcName, fullSpec, showReturns) {
+  const lines = [];
+  const allParams = operation.parameters || [];
+  const queryParamDefs = allParams.filter(p => p.in === 'query');
+  const hasBody = ['POST', 'PUT', 'PATCH'].includes(method) && !!operation.requestBody;
+  const rawBodySchema = hasBody
+    ? (operation.requestBody.content?.['application/json']?.schema
+      || Object.values(operation.requestBody.content || {})[0]?.schema)
+    : null;
+  const bodySchema = resolveRef(rawBodySchema, fullSpec);
+
+  const rawRespSchema = showReturns
+    ? (operation.responses?.['200']?.content?.['application/json']?.schema
+      || operation.responses?.['201']?.content?.['application/json']?.schema
+      || Object.values(operation.responses || {}).find(r => r.content)?.['content']?.['application/json']?.schema)
+    : null;
+  const respSchema = resolveRef(rawRespSchema, fullSpec);
+
+  lines.push('/**');
+
+  const title = operation.summary || operation.description || funcName;
+  lines.push(` * ${title}`);
+  if (operation.summary && operation.description && operation.description !== operation.summary) {
+    lines.push(' *');
+    lines.push(` * ${operation.description}`);
+  }
+  lines.push(' *');
+  lines.push(` * ${method.toUpperCase()} ${route}`);
+
+  const pathParamDefs = allParams.filter(p => p.in === 'path');
+  for (const p of pathParamDefs) {
+    const type = toJSDocType(p.schema, fullSpec);
+    const desc = p.description || '';
+    lines.push(` * @param {${type}} ${p.name}${desc ? ` - ${desc}` : ''}`);
+  }
+
+  if (queryParamDefs.length > 0) {
+    const hasRequired = queryParamDefs.some(p => p.required === true);
+    lines.push(` * @param {object} ${hasRequired ? '' : '['}params${hasRequired ? '' : ']'} - 查询参数`);
+    for (const p of queryParamDefs) {
+      const type = toJSDocType(p.schema, fullSpec);
+      const desc = p.description || '';
+      const req = p.required === true;
+      lines.push(` * @param {${type}} ${req ? '' : '['}params.${p.name}${req ? '' : ']'}${desc ? ` - ${desc}` : ''}`);
+    }
+  }
+
+  if (hasBody) {
+    const bodyRequired = operation.requestBody.required !== false;
+    const bodyDesc = operation.requestBody.description || '请求体';
+    const type = bodySchema ? toJSDocType(bodySchema, fullSpec) : 'object';
+    lines.push(` * @param {${type}} ${bodyRequired ? '' : '['}data${bodyRequired ? '' : ']'} - ${bodyDesc}`);
+    expandProperties(bodySchema, 'data', bodySchema?.required || [], fullSpec, lines, 0);
+  }
+
+  if (showReturns && respSchema) {
+    const respType = toJSDocType(respSchema, fullSpec);
+    lines.push(` * @returns {Promise<${respType}>} - 响应数据`);
+    expandProperties(respSchema, 'returns', respSchema?.required || [], fullSpec, lines, 0);
+  } else {
+    lines.push(' * @returns {Promise}');
+  }
+  lines.push(' */');
+
+  return lines.join('\n');
+}
+
+function expandProperties(schema, prefix, requiredList, fullSpec, lines, depth) {
+  if (depth > 3) return;
+  const resolved = resolveRef(schema, fullSpec);
+  if (resolved?.type !== 'object' || !resolved.properties) return;
+
+  const reqs = resolved.required || requiredList || [];
+  for (const [prop, propSchema] of Object.entries(resolved.properties)) {
+    const resolvedProp = resolveRef(propSchema, fullSpec);
+    const propType = toJSDocType(resolvedProp, fullSpec);
+    const propDesc = resolvedProp.description || '';
+    const req = reqs.includes(prop);
+    const fullPath = prefix ? `${prefix}.${prop}` : prop;
+    lines.push(` * @param {${propType}} ${req ? '' : '['}${fullPath}${req ? '' : ']'}${propDesc ? ` - ${propDesc}` : ''}`);
+
+    if (resolvedProp?.type === 'object' && resolvedProp.properties) {
+      expandProperties(resolvedProp, fullPath, resolvedProp.required || [], fullSpec, lines, depth + 1);
+    } else if (resolvedProp?.type === 'array' && resolvedProp.items) {
+      const resolvedItems = resolveRef(resolvedProp.items, fullSpec);
+      if (resolvedItems?.type === 'object' && resolvedItems.properties) {
+        expandProperties(resolvedItems, fullPath + '[]', resolvedItems.required || [], fullSpec, lines, depth + 1);
+      }
+    }
+  }
+}
+
+function generateJS(spec, outputDir, groupName, prefix, showReturns, importPath) {
+  const apiDir = path.join(outputDir, 'api');
+  fs.mkdirSync(apiDir, { recursive: true });
+
+  const paths = spec.paths || {};
+  const modules = {};
+  const pathPrefix = prefix || '';
+  const reqImport = importPath || '@/utils/request';
+
+  for (const [route, methods] of Object.entries(paths)) {
+    for (const [method, operation] of Object.entries(methods)) {
+      if (!operation || typeof operation !== 'object') continue;
+      let tags = operation.tags?.length ? operation.tags : null;
+      if (!tags) {
+        const seg = route.split('/').filter(Boolean)[0] || 'default';
+        tags = [seg];
+      }
+      for (const tag of tags) {
+        if (!modules[tag]) modules[tag] = [];
+        modules[tag].push({ route, method: method.toUpperCase(), operation });
+      }
+    }
+  }
+
+  const fileNames = [];
+
+  for (const [tag, apis] of Object.entries(modules)) {
+    let fileName;
+    if (groupName) {
+      fileName = groupName;
+    } else if (isAscii(tag) && tag !== 'default') {
+      fileName = tag.replace(/[^a-zA-Z0-9]/g, '_');
+    } else {
+      fileName = deriveModuleName(apis);
+    }
+    fileNames.push(fileName);
+
+    const lines = [
+      '/**',
+      ` * ${tag} 模块`,
+      ' * 由 pull-apifox 自动生成，请勿手动修改',
+      ' */',
+      '',
+      `import request from '${reqImport}';`,
+      '',
+    ];
+
+    for (const { route, method, operation } of apis) {
+      const funcName = toFuncName(operation, method, route);
+
+      const pathParams = (operation.parameters || []).filter(p => p.in === 'path').map(p => p.name);
+      const queryParams = (operation.parameters || []).filter(p => p.in === 'query').map(p => p.name);
+      const hasBody = ['POST', 'PUT', 'PATCH'].includes(method) && operation.requestBody;
+
+      const paramParts = [];
+      if (pathParams.length) paramParts.push(pathParams.join(', '));
+      if (queryParams.length) paramParts.push('params');
+      if (hasBody) paramParts.push('data');
+
+      lines.push(buildJSDoc(operation, method, route, funcName, spec, showReturns));
+      lines.push(`export function ${funcName}(${paramParts.join(', ')}) {`);
+
+      const fullPath = pathPrefix + route;
+      const urlExpr = pathParams.length
+        ? '`' + fullPath.replace(/\{(\w+)\}/g, '${$1}') + '`'
+        : `'${fullPath}'`;
+
+      lines.push('  return request({');
+      lines.push(`    url: ${urlExpr},`);
+      lines.push(`    method: '${method}',`);
+      if (queryParams.length) lines.push('    params,');
+      if (hasBody) {
+        const ct = Object.keys(operation.requestBody?.content || { 'application/json': {} })[0];
+        lines.push('    data,');
+        if (ct !== 'application/json') lines.push(`    headers: { 'Content-Type': '${ct}' },`);
+      }
+      lines.push('  });');
+      lines.push('}\n');
+    }
+
+    fs.writeFileSync(path.join(apiDir, `${fileName}.js`), lines.join('\n'), 'utf-8');
+    console.log(`   ✅ ${fileName}.js (${apis.length} 个接口)`);
+  }
+
+  if (fileNames.length > 0) {
+    const indexLines = fileNames
+      .map(name => `export * from './api/${name}';`)
+      .join('\n');
+    fs.writeFileSync(path.join(outputDir, 'index.js'), indexLines + '\n', 'utf-8');
+  } else {
+    console.log('   ⚠ 没有匹配到接口，请检查筛选条件（folder/tags/apis）是否正确');
+  }
+}
+
+// ======================== 主流程 ========================
+
+async function main() {
+  const configPath = process.argv[2] || path.join(process.cwd(), 'apifox.config.json');
+
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log('pull-apifox — 从 Apifox 拉取接口并生成 JS 代码');
+    console.log('');
+    console.log('用法:');
+    console.log('  pull-apifox                       使用当前目录下的 apifox.config.json');
+    console.log('  pull-apifox ./my-config.json      指定配置文件');
+    console.log('');
+    console.log('配置文档: https://github.com/xxx/pull-apifox');
+    process.exit(0);
+  }
+
+  if (!fs.existsSync(configPath)) {
+    console.error(`❌ 配置文件不存在: ${configPath}`);
+    console.error('   请在项目根目录创建 apifox.config.json，或指定路径: pull-apifox ./my-config.json');
+    process.exit(1);
+  }
+
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+
+  if (!config.projectId) {
+    console.error('❌ 配置文件缺少 projectId');
+    process.exit(1);
+  }
+
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  pull-apifox — Apifox 接口拉取 + JS 代码生成');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log(`  项目 ID: ${config.projectId}`);
+  console.log(`  拉取组数: ${config.pull.length}`);
+  console.log('');
+
+  console.log('📥 拉取完整 OpenAPI 规范...');
+  const fullSpec = await fetchSpec(config.projectId, null, config);
+  const totalPaths = Object.keys(fullSpec.paths || {}).length;
+  console.log(`   📊 项目共有 ${totalPaths} 个接口\n`);
+
+  const allTags = new Set();
+  for (const methods of Object.values(fullSpec.paths || {})) {
+    for (const op of Object.values(methods)) {
+      (op.tags || []).forEach(t => allTags.add(t));
+    }
+  }
+
+  const baseOutput = path.resolve(config.output || './src/apifox');
+
+  for (let i = 0; i < config.pull.length; i++) {
+    const group = config.pull[i];
+    const filterLabel = group.folder || group.tags?.join(', ') || '全部接口';
+    console.log(`📦 [${i + 1}/${config.pull.length}] ${filterLabel}`);
+
+    const filtered = filterSpec(fullSpec, group);
+
+    if (Object.keys(filtered.paths || {}).length === 0) {
+      const kw = group.folder || group.apis?.[0] || group.tags?.[0] || '';
+      if (kw) {
+        const matchedPaths = Object.keys(fullSpec.paths || {}).filter(p => p.toLowerCase().includes(kw.toLowerCase()));
+        if (matchedPaths.length > 0) {
+          console.log(`   💡 路径中包含「${kw}」的接口: ${matchedPaths.slice(0, 10).join(', ')}${matchedPaths.length > 10 ? '...' : ''}`);
+        }
+        const matchedTags = [...allTags].filter(t => t.toLowerCase().includes(kw.toLowerCase()));
+        if (matchedTags.length > 0) {
+          console.log(`   💡 标签中包含「${kw}」的: ${matchedTags.join(', ')}`);
+        }
+      }
+    }
+
+    generateJS(filtered, baseOutput, group.name, group.prefix, config.showReturns, config.importPath);
+    console.log('');
+  }
+
+  console.log('✅ 全部完成!');
+}
+
+// ======================== 导出 ========================
+
+module.exports = { main, fetchSpec, filterSpec, generateJS };

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "pull-apifox",
+  "version": "1.0.0",
+  "description": "从 Apifox 拉取接口并生成带 JSDoc 的 JS 请求代码",
+  "keywords": ["apifox", "openapi", "codegen", "api", "jsdoc"],
+  "license": "MIT",
+  "author": "fanwb1212",
+  "main": "lib/index.js",
+  "bin": {
+    "pull-apifox": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}