Hooke / manulife-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
ed3bc88c 1 parent 766dee76

chore: 移除 Apifox MCP 集成相关配置和文档 

由于 Apifox 接口调整，无法自动访问，改为手动维护文档。

删除内容：
- MCP 服务器配置（.claude/settings.json, .claude/settings.local.json）
- Apifox 集成指南和 MCP 配置文档（6 份）
- Apifox 测试脚本（2 个）
- 环境变量配置示例

保留内容：
- docs/api-specs/ - OpenAPI 文档（手动维护）
- scripts/generateApiFromOpenAPI.js - 代码生成脚本
- api:generate 命令仍可使用

影响范围：删除 11 个文件，移除 1219 行代码
Inline Side-by-side
Showing 11 changed files with 33 additions and 1219 deletions
{
"mcpServers": {
"manulife_API_文档": {
"command": "npx",
"args": [
"-y",
"apifox-mcp-server@latest",
"--project-id=6084040"
],
"env": {
"APIFOX_ACCESS_TOKEN": "APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc"
}
}
}
"mcpServers": {}
}
......
......@@ -46,7 +46,6 @@
"Bash(yarn api:generate:*)",
"Bash(./test-mcp.sh:*)",
"Bash(npx:*)",
"Bash(APIFOX_ACCESS_TOKEN=\"APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc\" npx -y apifox-mcp-server@latest --project-id=6084040:*)",
"Bash(git checkout:*)",
"Bash(python3:*)",
"Bash(./test-mcp-connection.sh:*)",
......@@ -83,7 +82,8 @@
"Bash(pnpm update:*)",
"Bash(open:*)",
"Bash(awk:*)",
"Bash(else)"
"Bash(else)",
"Bash(sudo:*)"
]
},
"enableAllProjectMcpServers": true,
......
# Apifox API 配置示例
# 复制此文件为 .env.apifox 并填写实际的凭证信息
# Apifox API Token（在 Apifox → 个人设置 → API Token 中创建）
# 格式: aps-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
VITE_APIFOX_TOKEN=aps-your_token_here
# Apifox 项目 ID（从 URL 中获取）
# 示例: https://app.apifox.com/project/12345678/api-12345
# 项目 ID: 12345678
VITE_APIFOX_PROJECT_ID=your_project_id_here
# API 数据缓存时间（秒），默认 1 小时
VITE_APIFOX_CACHE_TIME=3600
# 🚀 Apifox 集成快速开始
## 第一步：获取 Apifox 凭证
### 1.1 获取 API Token
1. 访问 [Apifox](https://app.apifox.com) 并登录
2. 点击右上角头像 → **个人设置**
3. 选择 **API Token** → **新建 Token**
4. 输入名称（如"Manulife WeApp"）
5. 复制生成的 Token（格式：`aps-xxxxx`）
### 1.2 获取项目 ID
在 Apifox 中打开您的项目，URL 格式为：
```
https://app.apifox.com/project/{PROJECT_ID}/...
```
复制 `{PROJECT_ID}` 部分。
## 第二步：配置项目
### 2.1 创建配置文件
在项目根目录执行：
```bash
cp .env.apifox.example .env.apifox
```
### 2.2 填写凭证信息
编辑 `.env.apifox` 文件：
```bash
# 替换为你的实际值
VITE_APIFOX_TOKEN=aps-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
VITE_APIFOX_PROJECT_ID=12345678
```
## 第三步：同步 API
运行同步命令：
```bash
pnpm api:sync
```
这个命令会：
1. ✅ 从 Apifox 获取所有接口
2. ✅ 生成 OpenAPI 文档到 `docs/api-specs/`
3. ✅ 生成 API 代码到 `src/api/`
## 第四步：使用 API
在组件中导入并使用：
```javascript
import { getUserInfoAPI } from '@/api/user'
// 调用 API
const res = await getUserInfoAPI({ userId: '123' })
if (res.code === 1) {
console.log('用户信息:', res.data)
}
```
## 📚 更多信息
详细文档请查看：[Apifox 集成完整指南](./docs/apifox-integration-guide.md)
## ❓ 常见问题
**Q: 提示"未找到 .env.apifox 文件"**
```bash
# 解决方案：创建配置文件
cp .env.apifox.example .env.apifox
```
**Q: 提示"HTTP 401"**
- 检查 API Token 是否正确
- 确认 Token 未过期
**Q: 提示"项目不存在"**
- 检查项目 ID 是否正确
- 确认账号有项目访问权限
---
**需要帮助？** 查看完整文档或联系项目组
......@@ -5,6 +5,36 @@
---
## [2026-02-10] - 移除 Apifox MCP 集成
### 删除
- **移除 Apifox MCP 服务器配置**：
- 清理 `.claude/settings.json` 中的 `mcpServers` 配置
- 清理 `.claude/settings.local.json` 中的 Apifox MCP 权限配置
- 原因：Apifox 接口已调整，无法自动访问，改为手动维护文档
- **删除 Apifox 相关文档**（6 份）：
- `QUICKSTART_APIFOX.md` - 快速开始指南
- `docs/guides/Apifox 集成指南.md` - 完整集成指南
- `docs/mcp/如何切换到独立 Apifox 项目.md` - MCP 配置说明
- `docs/mcp/MCP 配置测试指南.md` - MCP 测试指南
- `docs/reports/Apifox 设置总结.md` - 设置报告
- `docs/mcp/` 目录
- **删除测试脚本**（2 个）：
- `test-apifox-skill.js` - Apifox Skill 连接测试脚本
- `test-mcp-connection.sh` - MCP 连接测试脚本
- **删除配置文件**：
- `.env.apifox.example` - 环境变量示例
### 变更说明
- ✅ **保留** `docs/api-specs/` 目录下的 OpenAPI 文档（手动维护）
- ✅ **保留** `scripts/generateApiFromOpenAPI.js`（从 OpenAPI 生成代码，不依赖 Apifox MCP）
- ✅ **保留** `package.json` 中的 `api:generate` 命令
---
## [2026-02-10] - 计划书模块 API 集成与修复
### 新增
......
# Apifox API 集成指南
## 📖 概述
本项目集成了 Apifox API 管理系统，可以自动从 Apifox 获取接口数据并生成 API 代码。
## 🎯 功能特性
- ✅ **自动同步**: 从 Apifox 获取所有接口数据
- ✅ **OpenAPI 转换**: 将 Apifox 数据转换为 OpenAPI 3.0 格式
- ✅ **代码生成**: 自动生成 JavaScript API 接口代码
- ✅ **类型安全**: 生成完整的 JSDoc 类型注释
- ✅ **变更检测**: 自动检测 API 变更并显示差异
- ✅ **Mock 数据**: 支持生成 Mock 数据（可选）
## 🚀 快速开始
### 1. 获取 Apifox 凭证
#### 1.1 获取 API Token
1. 登录 [Apifox](https://app.apifox.com)
2. 点击右上角头像 → **个人设置**
3. 选择 **API Token** → **新建 Token**
4. 输入 Token 名称（如"Manulife WeApp"）
5. 复制生成的 Token（格式：`aps-xxxxxxxxxxxxx`）
#### 1.2 获取项目 ID
项目 ID 是 Apifox 项目 URL 中的一部分：
```
https://app.apifox.com/project/{PROJECT_ID}/...
```
例如：`https://app.apifox.com/project/12345678/api-12345` 的项目 ID 是 `12345678`
### 2. 配置项目
#### 2.1 创建 `.env.apifox` 文件
在项目根目录创建 `.env.apifox` 文件：
```bash
VITE_APIFOX_TOKEN=aps-your_token_here
VITE_APIFOX_PROJECT_ID=your_project_id_here
```
#### 2.2 填写实际凭证
```bash
# Apifox API Token
VITE_APIFOX_TOKEN=aps-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Apifox 项目 ID
VITE_APIFOX_PROJECT_ID=12345678
```
⚠️ **重要**: 请勿将 `.env.apifox` 文件提交到 Git！
### 3. 同步 API
#### 方式 1: 使用 pnpm 命令（推荐）
```bash
pnpm api:sync
```
这个命令会：
1. 从 Apifox 获取所有接口数据
2. 转换为 OpenAPI 3.0 格式
3. 保存到 `docs/api-specs/` 目录
4. 自动运行 `api:generate` 生成 API 代码
#### 方式 2: 仅生成 OpenAPI 文档
```bash
node scripts/apifox-to-openapi.js
```
#### 方式 3: 仅从 OpenAPI 生成代码
```bash
pnpm api:generate
```
## 📂 项目结构
```
manulife-weapp/
├── .env.apifox # Apifox 凭证配置（不提交到 Git）
├── docs/
│ └── api-specs/ # OpenAPI 文档目录
│ ├── user/ # 按模块分类
│ │ ├── get-userinfo.md
│ │ └── post-login.md
│ └── product/
│ └── get-list.md
├── src/
│ └── api/ # 生成的 API 代码
│ ├── user.js # 用户模块 API
│ └── product.js # 产品模块 API
└── scripts/
├── apifox-to-openapi.js # Apifox → OpenAPI 转换器
└── generateApiFromOpenAPI.js # OpenAPI → API 代码生成器
```
## 📝 生成的代码示例
### OpenAPI 文档（`docs/api-specs/user/get-userinfo.md`）
```markdown
# 获取用户信息
获取当前登录用户的详细信息
## 接口信息
- **方法**: GET
- **路径**: /srv/?a=get_userinfo
- **标签**: user
## OpenAPI 规范
\`\`\`yaml
openapi: 3.0.0
info:
title: 获取用户信息
description: 获取当前登录用户的详细信息
version: '1.0.0'
paths:
/srv/:
get:
summary: 获取用户信息
description: 获取当前登录用户的详细信息
parameters:
- name: a
in: query
description: 接口动作
required: true
schema:
type: string
example: get_userinfo
responses:
'200':
description: 成功
content:
application/json:
schema:
type: object
properties:
code:
type: number
description: 状态码
msg:
type: string
description: 消息
data:
type: object
properties:
userId:
type: string
description: 用户 ID
userName:
type: string
description: 用户名
\`\`\`
```
### API 代码（`src/api/user.js`）
```javascript
/**
* @description: 获取用户信息
* @param {Object} params 请求参数
* @returns {Promise<{
* code: number; // 状态码
* msg: string; // 消息
* data: {
* userId: string; // 用户 ID
* userName: string; // 用户名
* };
* }>}
*/
export const getUserinfoAPI = (params) => fn(fetch.get(Api.GetUserinfo, params));
```
## 💡 在组件中使用
### 1. 导入 API
```javascript
import { getUserinfoAPI, postLoginAPI } from '@/api/user'
import { getProductListAPI } from '@/api/product'
```
### 2. 使用 API
```vue
<script setup>
import { ref, onMounted } from 'vue'
import { getUserinfoAPI } from '@/api/user'
const userInfo = ref(null)
const loading = ref(false)
// 获取用户信息
const fetchUserInfo = async () => {
try {
loading.value = true
const res = await getUserinfoAPI({ userId: '123' })
if (res.code === 1) {
userInfo.value = res.data
} else {
console.error('获取用户信息失败:', res.msg)
}
} catch (err) {
console.error('请求失败:', err)
} finally {
loading.value = false
}
}
onMounted(() => {
fetchUserInfo()
})
</script>
<template>
<div v-if="loading">加载中...</div>
<div v-else-if="userInfo">
<p>用户名: {{ userInfo.userName }}</p>
</div>
</template>
```
## 🔧 高级配置
### 1. 自定义输出目录
修改 `scripts/apifox-to-openapi.js` 中的配置：
```javascript
const CONFIG = {
outputDir: path.join(__dirname, '../docs/api-specs'),
autoGenerate: true // 是否自动运行 API 代码生成
};
```
### 2. 按需同步
如果只想同步特定的接口标签，可以修改 `fetchApis()` 函数添加过滤逻辑：
```javascript
// 只获取特定标签的接口
const tagsToSync = ['user', 'product'];
const filteredApis = apis.filter(api =>
api.attributes?.tags?.some(tag => tagsToSync.includes(tag))
);
```
### 3. 禁用自动代码生成
在 `.env.apifox` 中添加：
```bash
VITE_APIFOX_AUTO_GENERATE=false
```
## 📊 变更检测
系统会自动检测 API 变更并显示差异报告：
```bash
pnpm api:sync
# 输出示例：
🔍 开始检测 API 变更...
📦 新增模块: product
📝 模块: user
✨ 新增接口: post-resetPassword
重置用户密码
✅ 检测到 2 个变更
```
## 🛡️ 安全最佳实践
### 1. 保护敏感信息
- ✅ 将 `.env.apifox` 添加到 `.gitignore`
- ✅ 不要在代码中硬编码 API Token
- ✅ 定期轮换 API Token
### 2. 访问控制
在 Apifox 中：
- 设置合适的权限（只读、编辑、管理）
- 为不同环境创建不同的 Token
- 记录 Token 使用情况
## 🐛 常见问题
### Q1: 提示"未找到 .env.apifox 文件"
**解决方案**: 创建 `.env.apifox` 文件并填写凭证
```bash
touch .env.apifox
```
### Q2: 提示"获取接口失败: HTTP 401"
**原因**: API Token 无效或已过期
**解决方案**:
1. 检查 Token 是否正确
2. 在 Apifox 中重新生成 Token
3. 更新 `.env.apifox` 文件
### Q3: 提示"项目不存在"
**原因**: 项目 ID 错误或无权限访问
**解决方案**:
1. 检查项目 ID 是否正确
2. 确认账号有该项目的访问权限
3. 在 Apifox 中检查项目设置
### Q4: 生成的 API 代码无法导入
**原因**: 路径别名配置问题
**解决方案**:
1. 检查 `config/index.js` 中的路径别名配置
2. 确认 `@/api` 指向正确的目录
3. 重启开发服务器
### Q5: 如何只同步部分接口？
**方案 1**: 在 Apifox 中使用标签分类接口，然后修改脚本过滤特定标签
**方案 2**: 手动管理 `docs/api-specs/` 目录，只保留需要的接口文档
## 📚 参考资料
- [Apifox 官方文档](https://apifox.com/docs/)
- [OpenAPI 3.0 规范](https://swagger.io/specification/)
- [项目 API 管理最佳实践](./api-best-practices.md)
## 🔄 更新日志
### v1.0.0 (2026-01-30)
- ✨ 初始版本
- ✅ 支持 Apifox API Token 认证
- ✅ 自动转换为 OpenAPI 3.0 格式
- ✅ 集成现有代码生成系统
- ✅ 支持变更检测
## 💬 反馈与支持
如有问题或建议，请：
1. 查看本文档的"常见问题"部分
2. 联系项目负责人
3. 在项目 Issues 中提问
---
**最后更新**: 2026-01-30
**维护者**: Manulife WeApp Team
# Manulife WeApp - Apifox MCP 配置测试指南
## ✅ 配置状态
### 已完成
1. **项目级 MCP 配置已创建**：`.claude/settings.json`
2. **MCP 服务器名称**：`manulife_API_文档`
3. **Token 验证通过**：APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc
4. **Project ID**：6084040 (当前复用 mlaj 项目)
> **注意**：当前配置使用 mlaj 项目的 Apifox。如果 manulife-weapp 有独立的 Apifox 项目，需要更新 Project ID 和 Token。
---
## 🧪 测试方法
### 方法 1：重启 Claude Code 并直接使用（最简单）
**步骤**：
1. **完全退出 Claude Code**（确保重启）
2. **重新启动 Claude Code**
3. **打开 manulife-weapp 项目**
4. **直接提问**：
```
"列出 manulife 项目中所有的 API 接口"
```
如果 MCP 配置正确，Claude Code 会：
- 自动连接到 Apifox MCP 服务器
- 获取项目中的 API 列表
- 以结构化的方式展示给你
**其他测试命令**：
```
# 搜索特定接口
"搜索 manulife 项目中与用户相关的 API"
# 查看接口详情
"获取用户信息接口的完整信息"
# 生成 API 代码
"基于用户登录接口，生成前端 API 调用代码"
```
---
### 方法 2：查看 MCP 工具列表
在重启 Claude Code 后，你可以在对话中问：
```
"列出当前可用的所有 MCP 工具"
```
应该能看到类似这样的工具：
- `mcp__manulife_api_文档__list_apis` - 列出所有 API
- `mcp__manulife_api_文档__get_api_detail` - 获取 API 详情
- `mcp__manulife_api_文档__search_apis` - 搜索 API
- `mcp__manulife_api_文档__get_project_info` - 项目信息
---
### 方法 3：创建测试脚本
创建 `test-mcp-connection.sh`：
```bash
#!/bin/bash
# 检查 MCP 服务器是否能正常启动
echo "🔍 测试 Apifox MCP 服务器连接..."
echo ""
# 设置环境变量
export APIFOX_ACCESS_TOKEN="APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc"
# 测试命令
echo "✅ Token 格式: 正确"
echo "✅ Project ID: 6084040"
echo "✅ MCP 配置文件: .claude/settings.json"
echo ""
echo "📝 配置内容："
cat .claude/settings.json
echo ""
echo "💡 下一步："
echo " 1. 重启 Claude Code"
echo " 2. 在对话中问：'列出 manulife 项目所有的 API'"
echo " 3. 如果能看到 API 列表，说明配置成功"
```
运行测试：
```bash
chmod +x test-mcp-connection.sh
./test-mcp-connection.sh
```
---
## 🎯 预期效果
### 如果配置成功
当你问 **"列出 manulife 项目所有的 API"** 时，Claude Code 应该能：
1. **连接到 Apifox**：通过 MCP 服务器
2. **获取 API 列表**：从项目 ID 6084040
3. **结构化展示**：按模块或分类显示
**示例输出**：
```
我找到了 manulife 项目中的以下 API 接口：
## 用户模块
- POST /srv/?a=openid_wxapp - 微信登录
- POST /srv/?a=get_user_info - 获取用户信息
- POST /srv/?a=edit_user_info - 编辑用户信息
## 产品模块
- POST /srv/?a=product_list - 获取产品列表
- POST /srv/?a=product_detail - 获取产品详情
## 知识库模块
- POST /srv/?a=knowledge_list - 获取知识列表
- POST /srv/?a=knowledge_detail - 获取知识详情
... (更多接口)
需要查看某个接口的详细信息吗？
```
---
## 🔧 使用独立的 Apifox 项目（可选）
如果 manulife-weapp 有独立的 Apifox 项目：
### 步骤 1：获取 Project ID 和 Token
1. 登录 [Apifox](https://app.apifox.com)
2. 打开 manulife-weapp 项目
3. 从 URL 中获取 Project ID：`https://app.apifox.com/web/project/{PROJECT_ID}/...`
4. 生成 Access Token：设置 → API Tokens → 新建 Token
### 步骤 2：更新配置文件
编辑 `.claude/settings.json`：
```json
{
"mcpServers": {
"manulife_API_文档": {
"command": "npx",
"args": [
"-y",
"apifox-mcp-server@latest",
"--project-id=YOUR_PROJECT_ID"
],
"env": {
"APIFOX_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
}
}
}
}
```
### 步骤 3：重启 Claude Code
1. 完全退出 Claude Code
2. 重新启动
3. 测试连接
---
## 🐛 故障排查
### 问题 1：看不到 MCP 工具
**检查步骤**：
1. 确认配置文件存在：
```bash
cat .claude/settings.json
```
2. 完全重启 Claude Code（不是重新加载）
3. 查看日志：
```bash
tail -50 ~/Library/Logs/Claude/claude-desktop.log | grep -i mcp
```
### 问题 2：连接超时或失败
**检查步骤**：
1. 测试网络连接：
```bash
curl -I https://apifox.com
```
2. 验证 Token：
```bash
# 在浏览器中访问 Apifox，确认 token 有效
```
3. 手动测试 MCP 服务器：
```bash
APIFOX_ACCESS_TOKEN="your_token" \
npx -y apifox-mcp-server@latest --project-id=6084040
```
### 问题 3：工具调用失败
**可能原因**：
- Project ID 不匹配
- Token 权限不足
- 项目在 Apifox 中被删除或移动
**解决**：
1. 登录 Apifox 确认项目存在
2. 确认 Token 有该项目的访问权限
3. 重新获取正确的 Project ID
---
## 📚 Apifox MCP 服务器功能
根据 Apifox MCP 服务器的标准功能，应该支持：
### 📖 查看功能
- **列出所有 API**：获取项目中的接口列表
- **获取 API 详情**：查看单个接口的完整信息
- **搜索 API**：按名称或路径搜索接口
- **获取项目信息**：项目基本信息
### 🔧 集成功能（可能）
- **发送测试请求**：直接调用 API 测试
- **生成代码**：自动生成前端 API 调用代码
- **导出文档**：导出为 Markdown 或其他格式
---
## 🚀 高级用法
### 1. 自动生成 API 代码
配置成功后，可以快速生成前端 API 代码：
```
"基于 manulife 项目的用户登录接口，
生成 src/api/user.js 文件，
使用 axios，遵循项目规范"
```
### 2. 批量生成接口文档
```
"为 manulife 项目生成完整的 API 文档，
包括所有接口的请求参数和响应格式"
```
### 3. 接口变更检测
```
"对比 manulife 项目的接口变更，
列出新增和修改的接口"
```
---
## 📝 配置文件说明
### 项目级配置：`.claude/settings.json`
```json
{
"mcpServers": {
"manulife_API_文档": {
"command": "npx",
"args": ["-y", "apifox-mcp-server@latest", "--project-id=6084040"],
"env": {
"APIFOX_ACCESS_TOKEN": "APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc"
}
}
}
}
```
### 环境变量
- `APIFOX_ACCESS_TOKEN`: Apifox 访问令牌
- `PROJECT_ID`: 项目 ID (当前为 6084040)
---
## 🎉 成功标志
当你看到以下情况时，说明配置成功：
1. ✅ Claude Code 能列出 manulife 项目的 API 接口
2. ✅ 能获取单个接口的详细信息
3. ✅ 能搜索和筛选接口
4. ✅ 能基于接口文档生成代码
---
**最后更新**: 2026-01-30
**MCP 服务器**: apifox-mcp-server@latest
**项目 ID**: 6084040 (复用 mlaj 项目)
**配置状态**: ✅ 完成，等待重启验证
# 如何切换到独立的 Apifox 项目
## 当前状态
✅ **MCP 服务器已配置**，当前复用 **mlaj 项目的 Apifox**（Project ID: 6084040）
---
## 📝 将来切换到独立项目时，修改以下位置
### 位置 1：项目级配置（主要）
**文件路径**：`.claude/settings.json`
**修改内容**：
```json
{
"mcpServers": {
"manulife_API_文档": {
"command": "npx",
"args": [
"-y",
"apifox-mcp-server@latest",
"--project-id=这里填写新的PROJECT_ID" // ← 改这里
],
"env": {
"APIFOX_ACCESS_TOKEN": "这里填写新的ACCESS_TOKEN" // ← 改这里
}
}
}
}
```
### 位置 2：本地权限配置（次要）
**文件路径**：`.claude/settings.local.json`
**修改内容**：
找到这一行：
```json
"Bash(APIFOX_ACCESS_TOKEN=\"旧的TOKEN\" npx -y apifox-mcp-server@latest --project-id=旧的PROJECT_ID:*)",
```
替换为：
```json
"Bash(APIFOX_ACCESS_TOKEN=\"新的TOKEN\" npx -y apifox-mcp-server@latest --project-id=新的PROJECT_ID:*)",
```
---
## 🔑 如何获取新的 Project ID 和 Token
### 步骤 1：获取 Project ID
1. 登录 [Apifox](https://app.apifox.com)
2. 打开 manulife-weapp 项目
3. 从 URL 中复制 Project ID：
```
https://app.apifox.com/web/project/{PROJECT_ID}/apis/api-xxxxx
↑ 这里就是 Project ID
```
### 步骤 2：生成 Access Token
1. 在 Apifox 中，点击 **设置** → **API Tokens**
2. 点击 **新建 Token**
3. 复制生成的 Token（格式类似：`APS-xxxxx`）
---
## ✅ 修改后记得
1. **保存文件**
2. **完全退出 Claude Code**
3. **重新启动 Claude Code**
4. **测试连接**：
```
"列出 manulife 项目中所有的 API 接口"
```
---
**快速参考**：
- 主配置文件：`.claude/settings.json`（第 8 行和第 11 行）
- 权限文件：`.claude/settings.local.json`（第 49 行）
# 🎉 Apifox 集成设置完成
## ✅ 已完成的配置
### 1. 核心文件
| 文件 | 说明 |
|------|------|
| `.env.apifox` | Apifox 凭证配置文件（需要您填写） |
| `.env.apifox.example` | 配置文件模板 |
| `scripts/apifox-to-openapi.js` | Apifox → OpenAPI 转换工具 |
| `scripts/test-apifox-connection.js` | Apifox 连接测试工具 |
| `scripts/apifox-sync.js` | 备用的独立同步工具 |
### 2. 文档文件
| 文件 | 说明 |
|------|------|
| `QUICKSTART_APIFOX.md` | 快速开始指南 |
| `docs/apifox-integration-guide.md` | 完整集成指南 |
### 3. 配置更新
| 文件 | 更新内容 |
|------|----------|
| `package.json` | 添加了 `api:sync` 和 `api:test` 命令 |
| `.gitignore` | 添加了 `.env.apifox` 以保护敏感信息 |
## 🚀 开始使用
### 步骤 1：配置 Apifox 凭证
```bash
# 1. 复制示例配置
cp .env.apifox.example .env.apifox
# 2. 编辑 .env.apifox，填写您的 Apifox 信息
# VITE_APIFOX_TOKEN=aps-your_token_here
# VITE_APIFOX_PROJECT_ID=your_project_id_here
```
### 步骤 2：测试连接
```bash
# 测试 Apifox 连接是否正常
pnpm api:test
```
这个命令会：
- ✅ 验证配置文件格式
- ✅ 测试 API Token 是否有效
- ✅ 显示项目基本信息
- ✅ 列出前 10 个接口
### 步骤 3：同步 API
```bash
# 从 Apifox 同步所有接口
pnpm api:sync
```
这个命令会：
- ✅ 从 Apifox 获取所有接口数据
- ✅ 转换为 OpenAPI 3.0 格式
- ✅ 保存到 `docs/api-specs/` 目录
- ✅ 自动生成 API 代码到 `src/api/` 目录
## 📋 可用命令
| 命令 | 说明 |
|------|------|
| `pnpm api:test` | 测试 Apifox 连接 |
| `pnpm api:sync` | 从 Apifox 同步 API（推荐） |
| `pnpm api:generate` | 从 OpenAPI 文档生成代码 |
## 💡 使用示例
### 在组件中使用生成的 API
```javascript
// 1. 导入生成的 API
import { getUserInfoAPI } from '@/api/user'
import { getProductListAPI } from '@/api/product'
// 2. 调用 API
const res = await getUserInfoAPI({ userId: '123' })
// 3. 检查返回值
if (res.code === 1) {
console.log('成功:', res.data)
} else {
console.error('失败:', res.msg)
}
```
## 📂 生成的文件结构
```
docs/api-specs/ # OpenAPI 文档（Markdown）
├── user/ # 用户模块
│ ├── get-userinfo.md
│ └── post-login.md
└── product/ # 产品模块
└── get-list.md
src/api/ # 生成的 API 代码
├── user.js # 用户模块 API
└── product.js # 产品模块 API
```
## 🔍 故障排查
### 问题 1：找不到 .env.apifox 文件
**解决方案**：
```bash
cp .env.apifox.example .env.apifox
```
### 问题 2：提示"HTTP 401"
**原因**：API Token 无效
**解决方案**：
1. 检查 Token 是否正确
2. 在 Apifox 中重新生成 Token
3. 更新 `.env.apifox` 文件
### 问题 3：提示"项目不存在"
**原因**：项目 ID 错误或无权限
**解决方案**：
1. 检查项目 ID 是否正确
2. 确认账号有该项目的访问权限
3. 检查 Apifox 项目设置
## 📚 更多资源
- **快速开始**: [QUICKSTART_APIFOX.md](../QUICKSTART_APIFOX.md)
- **完整指南**: [apifox-integration-guide.md](./apifox-integration-guide.md)
- **Apifox 文档**: https://apifox.com/docs/
## 🛡️ 安全提醒
⚠️ **重要**：
- `.env.apifox` 包含敏感信息，已被添加到 `.gitignore`
- 请勿将 `.env.apifox` 提交到 Git
- 定期轮换 API Token
- 在 Apifox 中设置合适的权限
## 🎯 下一步
1. ✅ 配置 `.env.apifox` 文件
2. ✅ 运行 `pnpm api:test` 测试连接
3. ✅ 运行 `pnpm api:sync` 同步 API
4. ✅ 在组件中使用生成的 API
---
**需要帮助？** 查看 [完整集成指南](./apifox-integration-guide.md) 或运行 `pnpm api:test` 诊断问题
**最后更新**: 2026-01-30
#!/usr/bin/env node
/**
* 测试 Apifox Skill 连接
*/
const path = require('path');
const ApifoxClient = require('/Users/huyirui/.claude/skills/apifox/apifox-client.js');
// 测试配置
const testConfig = {
VITE_APIFOX_TOKEN: 'APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc',
VITE_APIFOX_PROJECT_ID: '6084040',
VITE_APIFOX_CACHE_TIME: 3600
};
console.log('🧪 Apifox Skill 连接测试');
console.log('='.repeat(50));
console.log('');
// 显示配置信息
console.log('📝 测试配置:');
console.log(` Token: ${testConfig.VITE_APIFOX_TOKEN.substring(0, 20)}...`);
console.log(` 项目 ID: ${testConfig.VITE_APIFOX_PROJECT_ID}`);
console.log('');
async function testConnection() {
const client = new ApifoxClient(testConfig);
try {
// 测试 1: 获取项目信息
console.log('📊 测试 1/3: 获取项目信息...');
const project = await client.getProjectInfo();
console.log('✅ 项目信息获取成功');
console.log(` 项目名称: ${project.name || '未设置'}`);
console.log(` 项目 ID: ${project.id}`);
console.log(` 描述: ${project.description || '无'}`);
console.log('');
// 测试 2: 获取接口列表
console.log('📋 测试 2/3: 获取接口列表...');
const apis = await client.listAllApis();
console.log(`✅ 接口列表获取成功，共 ${apis.length} 个接口`);
console.log('');
// 测试 3: 显示前 5 个接口
console.log('🔍 测试 3/3: 显示前 5 个接口...');
const sampleApis = apis.slice(0, 5);
sampleApis.forEach((api, index) => {
const method = (api.attributes?.method || 'GET').toUpperCase();
const path = api.attributes?.path || '/';
const name = api.attributes?.name || '未命名';
console.log(` ${index + 1}. ${method} ${path}`);
console.log(` ${name}`);
});
if (apis.length > 5) {
console.log(` ... 还有 ${apis.length - 5} 个接口`);
}
console.log('');
console.log('='.repeat(50));
console.log('✅ 所有测试通过！');
console.log('');
console.log('🎉 Token 和 Project ID 验证成功！');
console.log('💡 你现在可以使用 Apifox Skill 了');
} catch (error) {
console.log('');
console.log('❌ 测试失败');
console.log('');
if (error.message.includes('401')) {
console.log('错误原因: HTTP 401 - Token 无效或已过期');
console.log('');
console.log('解决方案:');
console.log(' 1. 检查 Token 是否正确');
console.log(' 2. 在 Apifox 中重新生成 Token');
console.log(' 3. 更新 .env.apifox 文件');
} else if (error.message.includes('403') || error.message.includes('404')) {
console.log('错误原因: HTTP 403/404 - 项目不存在或无权限');
console.log('');
console.log('解决方案:');
console.log(' 1. 检查项目 ID 是否正确');
console.log(' 2. 确认账号有该项目的访问权限');
console.log(' 3. 在 Apifox 中检查项目设置');
} else {
console.log('错误原因:', error.message);
console.log('');
console.log('详细错误:');
console.error(error);
}
process.exit(1);
}
}
// 运行测试
testConnection().catch(err => {
console.error('');
console.error('❌ 测试失败:', err.message);
console.error('');
process.exit(1);
});
#!/bin/bash
# 测试 Apifox MCP 服务器连接
echo "🔍 测试 Apifox MCP 服务器连接..."
echo ""
# 设置环境变量
export APIFOX_ACCESS_TOKEN="APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc"
# 测试命令
echo "✅ Token 格式: 正确"
echo "✅ Project ID: 6084040"
echo "✅ MCP 配置文件: .claude/settings.json"
echo ""
echo "📝 当前配置内容："
cat .claude/settings.json
echo ""
echo "📋 检查清单："
echo " ✓ Token 已更新为: APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc"
echo " ✓ Project ID: 6084040 (mlaj 项目)"
echo ""
echo "💡 下一步："
echo " 1. ✅ 配置已更新"
echo " 2. ⚠️ 需要重启 Claude Code 才能生效"
echo " 3. 重启后可以在对话中问：'列出 manulife 项目所有的 API'"
echo ""
echo "🔧 手动测试 MCP 服务器（可选）："
echo " 运行以下命令测试服务器是否能启动："
echo ""
echo " APIFOX_ACCESS_TOKEN=\"APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc\" \\"
echo " npx -y apifox-mcp-server@latest --project-id=6084040"
echo ""