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 行代码
Showing
11 changed files
with
33 additions
and
1219 deletions
| 1 | { | 1 | { |
| 2 | - "mcpServers": { | 2 | + "mcpServers": {} |
| 3 | - "manulife_API_文档": { | ||
| 4 | - "command": "npx", | ||
| 5 | - "args": [ | ||
| 6 | - "-y", | ||
| 7 | - "apifox-mcp-server@latest", | ||
| 8 | - "--project-id=6084040" | ||
| 9 | - ], | ||
| 10 | - "env": { | ||
| 11 | - "APIFOX_ACCESS_TOKEN": "APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc" | ||
| 12 | - } | ||
| 13 | - } | ||
| 14 | - } | ||
| 15 | } | 3 | } | ... | ... |
| ... | @@ -46,7 +46,6 @@ | ... | @@ -46,7 +46,6 @@ |
| 46 | "Bash(yarn api:generate:*)", | 46 | "Bash(yarn api:generate:*)", |
| 47 | "Bash(./test-mcp.sh:*)", | 47 | "Bash(./test-mcp.sh:*)", |
| 48 | "Bash(npx:*)", | 48 | "Bash(npx:*)", |
| 49 | - "Bash(APIFOX_ACCESS_TOKEN=\"APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc\" npx -y apifox-mcp-server@latest --project-id=6084040:*)", | ||
| 50 | "Bash(git checkout:*)", | 49 | "Bash(git checkout:*)", |
| 51 | "Bash(python3:*)", | 50 | "Bash(python3:*)", |
| 52 | "Bash(./test-mcp-connection.sh:*)", | 51 | "Bash(./test-mcp-connection.sh:*)", |
| ... | @@ -83,7 +82,8 @@ | ... | @@ -83,7 +82,8 @@ |
| 83 | "Bash(pnpm update:*)", | 82 | "Bash(pnpm update:*)", |
| 84 | "Bash(open:*)", | 83 | "Bash(open:*)", |
| 85 | "Bash(awk:*)", | 84 | "Bash(awk:*)", |
| 86 | - "Bash(else)" | 85 | + "Bash(else)", |
| 86 | + "Bash(sudo:*)" | ||
| 87 | ] | 87 | ] |
| 88 | }, | 88 | }, |
| 89 | "enableAllProjectMcpServers": true, | 89 | "enableAllProjectMcpServers": true, | ... | ... |
.env.apifox.example
deleted
100644 → 0
| 1 | -# Apifox API 配置示例 | ||
| 2 | -# 复制此文件为 .env.apifox 并填写实际的凭证信息 | ||
| 3 | - | ||
| 4 | -# Apifox API Token(在 Apifox → 个人设置 → API Token 中创建) | ||
| 5 | -# 格式: aps-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | ||
| 6 | -VITE_APIFOX_TOKEN=aps-your_token_here | ||
| 7 | - | ||
| 8 | -# Apifox 项目 ID(从 URL 中获取) | ||
| 9 | -# 示例: https://app.apifox.com/project/12345678/api-12345 | ||
| 10 | -# 项目 ID: 12345678 | ||
| 11 | -VITE_APIFOX_PROJECT_ID=your_project_id_here | ||
| 12 | - | ||
| 13 | -# API 数据缓存时间(秒),默认 1 小时 | ||
| 14 | -VITE_APIFOX_CACHE_TIME=3600 |
QUICKSTART_APIFOX.md
deleted
100644 → 0
| 1 | -# 🚀 Apifox 集成快速开始 | ||
| 2 | - | ||
| 3 | -## 第一步:获取 Apifox 凭证 | ||
| 4 | - | ||
| 5 | -### 1.1 获取 API Token | ||
| 6 | - | ||
| 7 | -1. 访问 [Apifox](https://app.apifox.com) 并登录 | ||
| 8 | -2. 点击右上角头像 → **个人设置** | ||
| 9 | -3. 选择 **API Token** → **新建 Token** | ||
| 10 | -4. 输入名称(如"Manulife WeApp") | ||
| 11 | -5. 复制生成的 Token(格式:`aps-xxxxx`) | ||
| 12 | - | ||
| 13 | -### 1.2 获取项目 ID | ||
| 14 | - | ||
| 15 | -在 Apifox 中打开您的项目,URL 格式为: | ||
| 16 | - | ||
| 17 | -``` | ||
| 18 | -https://app.apifox.com/project/{PROJECT_ID}/... | ||
| 19 | -``` | ||
| 20 | - | ||
| 21 | -复制 `{PROJECT_ID}` 部分。 | ||
| 22 | - | ||
| 23 | -## 第二步:配置项目 | ||
| 24 | - | ||
| 25 | -### 2.1 创建配置文件 | ||
| 26 | - | ||
| 27 | -在项目根目录执行: | ||
| 28 | - | ||
| 29 | -```bash | ||
| 30 | -cp .env.apifox.example .env.apifox | ||
| 31 | -``` | ||
| 32 | - | ||
| 33 | -### 2.2 填写凭证信息 | ||
| 34 | - | ||
| 35 | -编辑 `.env.apifox` 文件: | ||
| 36 | - | ||
| 37 | -```bash | ||
| 38 | -# 替换为你的实际值 | ||
| 39 | -VITE_APIFOX_TOKEN=aps-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | ||
| 40 | -VITE_APIFOX_PROJECT_ID=12345678 | ||
| 41 | -``` | ||
| 42 | - | ||
| 43 | -## 第三步:同步 API | ||
| 44 | - | ||
| 45 | -运行同步命令: | ||
| 46 | - | ||
| 47 | -```bash | ||
| 48 | -pnpm api:sync | ||
| 49 | -``` | ||
| 50 | - | ||
| 51 | -这个命令会: | ||
| 52 | -1. ✅ 从 Apifox 获取所有接口 | ||
| 53 | -2. ✅ 生成 OpenAPI 文档到 `docs/api-specs/` | ||
| 54 | -3. ✅ 生成 API 代码到 `src/api/` | ||
| 55 | - | ||
| 56 | -## 第四步:使用 API | ||
| 57 | - | ||
| 58 | -在组件中导入并使用: | ||
| 59 | - | ||
| 60 | -```javascript | ||
| 61 | -import { getUserInfoAPI } from '@/api/user' | ||
| 62 | - | ||
| 63 | -// 调用 API | ||
| 64 | -const res = await getUserInfoAPI({ userId: '123' }) | ||
| 65 | -if (res.code === 1) { | ||
| 66 | - console.log('用户信息:', res.data) | ||
| 67 | -} | ||
| 68 | -``` | ||
| 69 | - | ||
| 70 | -## 📚 更多信息 | ||
| 71 | - | ||
| 72 | -详细文档请查看:[Apifox 集成完整指南](./docs/apifox-integration-guide.md) | ||
| 73 | - | ||
| 74 | -## ❓ 常见问题 | ||
| 75 | - | ||
| 76 | -**Q: 提示"未找到 .env.apifox 文件"** | ||
| 77 | -```bash | ||
| 78 | -# 解决方案:创建配置文件 | ||
| 79 | -cp .env.apifox.example .env.apifox | ||
| 80 | -``` | ||
| 81 | - | ||
| 82 | -**Q: 提示"HTTP 401"** | ||
| 83 | -- 检查 API Token 是否正确 | ||
| 84 | -- 确认 Token 未过期 | ||
| 85 | - | ||
| 86 | -**Q: 提示"项目不存在"** | ||
| 87 | -- 检查项目 ID 是否正确 | ||
| 88 | -- 确认账号有项目访问权限 | ||
| 89 | - | ||
| 90 | ---- | ||
| 91 | - | ||
| 92 | -**需要帮助?** 查看完整文档或联系项目组 |
| ... | @@ -5,6 +5,36 @@ | ... | @@ -5,6 +5,36 @@ |
| 5 | 5 | ||
| 6 | --- | 6 | --- |
| 7 | 7 | ||
| 8 | +## [2026-02-10] - 移除 Apifox MCP 集成 | ||
| 9 | + | ||
| 10 | +### 删除 | ||
| 11 | +- **移除 Apifox MCP 服务器配置**: | ||
| 12 | + - 清理 `.claude/settings.json` 中的 `mcpServers` 配置 | ||
| 13 | + - 清理 `.claude/settings.local.json` 中的 Apifox MCP 权限配置 | ||
| 14 | + - 原因:Apifox 接口已调整,无法自动访问,改为手动维护文档 | ||
| 15 | + | ||
| 16 | +- **删除 Apifox 相关文档**(6 份): | ||
| 17 | + - `QUICKSTART_APIFOX.md` - 快速开始指南 | ||
| 18 | + - `docs/guides/Apifox 集成指南.md` - 完整集成指南 | ||
| 19 | + - `docs/mcp/如何切换到独立 Apifox 项目.md` - MCP 配置说明 | ||
| 20 | + - `docs/mcp/MCP 配置测试指南.md` - MCP 测试指南 | ||
| 21 | + - `docs/reports/Apifox 设置总结.md` - 设置报告 | ||
| 22 | + - `docs/mcp/` 目录 | ||
| 23 | + | ||
| 24 | +- **删除测试脚本**(2 个): | ||
| 25 | + - `test-apifox-skill.js` - Apifox Skill 连接测试脚本 | ||
| 26 | + - `test-mcp-connection.sh` - MCP 连接测试脚本 | ||
| 27 | + | ||
| 28 | +- **删除配置文件**: | ||
| 29 | + - `.env.apifox.example` - 环境变量示例 | ||
| 30 | + | ||
| 31 | +### 变更说明 | ||
| 32 | +- ✅ **保留** `docs/api-specs/` 目录下的 OpenAPI 文档(手动维护) | ||
| 33 | +- ✅ **保留** `scripts/generateApiFromOpenAPI.js`(从 OpenAPI 生成代码,不依赖 Apifox MCP) | ||
| 34 | +- ✅ **保留** `package.json` 中的 `api:generate` 命令 | ||
| 35 | + | ||
| 36 | +--- | ||
| 37 | + | ||
| 8 | ## [2026-02-10] - 计划书模块 API 集成与修复 | 38 | ## [2026-02-10] - 计划书模块 API 集成与修复 |
| 9 | 39 | ||
| 10 | ### 新增 | 40 | ### 新增 | ... | ... |
docs/guides/Apifox 集成指南.md
deleted
100644 → 0
| 1 | -# Apifox API 集成指南 | ||
| 2 | - | ||
| 3 | -## 📖 概述 | ||
| 4 | - | ||
| 5 | -本项目集成了 Apifox API 管理系统,可以自动从 Apifox 获取接口数据并生成 API 代码。 | ||
| 6 | - | ||
| 7 | -## 🎯 功能特性 | ||
| 8 | - | ||
| 9 | -- ✅ **自动同步**: 从 Apifox 获取所有接口数据 | ||
| 10 | -- ✅ **OpenAPI 转换**: 将 Apifox 数据转换为 OpenAPI 3.0 格式 | ||
| 11 | -- ✅ **代码生成**: 自动生成 JavaScript API 接口代码 | ||
| 12 | -- ✅ **类型安全**: 生成完整的 JSDoc 类型注释 | ||
| 13 | -- ✅ **变更检测**: 自动检测 API 变更并显示差异 | ||
| 14 | -- ✅ **Mock 数据**: 支持生成 Mock 数据(可选) | ||
| 15 | - | ||
| 16 | -## 🚀 快速开始 | ||
| 17 | - | ||
| 18 | -### 1. 获取 Apifox 凭证 | ||
| 19 | - | ||
| 20 | -#### 1.1 获取 API Token | ||
| 21 | - | ||
| 22 | -1. 登录 [Apifox](https://app.apifox.com) | ||
| 23 | -2. 点击右上角头像 → **个人设置** | ||
| 24 | -3. 选择 **API Token** → **新建 Token** | ||
| 25 | -4. 输入 Token 名称(如"Manulife WeApp") | ||
| 26 | -5. 复制生成的 Token(格式:`aps-xxxxxxxxxxxxx`) | ||
| 27 | - | ||
| 28 | -#### 1.2 获取项目 ID | ||
| 29 | - | ||
| 30 | -项目 ID 是 Apifox 项目 URL 中的一部分: | ||
| 31 | - | ||
| 32 | -``` | ||
| 33 | -https://app.apifox.com/project/{PROJECT_ID}/... | ||
| 34 | -``` | ||
| 35 | - | ||
| 36 | -例如:`https://app.apifox.com/project/12345678/api-12345` 的项目 ID 是 `12345678` | ||
| 37 | - | ||
| 38 | -### 2. 配置项目 | ||
| 39 | - | ||
| 40 | -#### 2.1 创建 `.env.apifox` 文件 | ||
| 41 | - | ||
| 42 | -在项目根目录创建 `.env.apifox` 文件: | ||
| 43 | - | ||
| 44 | -```bash | ||
| 45 | -VITE_APIFOX_TOKEN=aps-your_token_here | ||
| 46 | -VITE_APIFOX_PROJECT_ID=your_project_id_here | ||
| 47 | -``` | ||
| 48 | - | ||
| 49 | -#### 2.2 填写实际凭证 | ||
| 50 | - | ||
| 51 | -```bash | ||
| 52 | -# Apifox API Token | ||
| 53 | -VITE_APIFOX_TOKEN=aps-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | ||
| 54 | - | ||
| 55 | -# Apifox 项目 ID | ||
| 56 | -VITE_APIFOX_PROJECT_ID=12345678 | ||
| 57 | -``` | ||
| 58 | - | ||
| 59 | -⚠️ **重要**: 请勿将 `.env.apifox` 文件提交到 Git! | ||
| 60 | - | ||
| 61 | -### 3. 同步 API | ||
| 62 | - | ||
| 63 | -#### 方式 1: 使用 pnpm 命令(推荐) | ||
| 64 | - | ||
| 65 | -```bash | ||
| 66 | -pnpm api:sync | ||
| 67 | -``` | ||
| 68 | - | ||
| 69 | -这个命令会: | ||
| 70 | -1. 从 Apifox 获取所有接口数据 | ||
| 71 | -2. 转换为 OpenAPI 3.0 格式 | ||
| 72 | -3. 保存到 `docs/api-specs/` 目录 | ||
| 73 | -4. 自动运行 `api:generate` 生成 API 代码 | ||
| 74 | - | ||
| 75 | -#### 方式 2: 仅生成 OpenAPI 文档 | ||
| 76 | - | ||
| 77 | -```bash | ||
| 78 | -node scripts/apifox-to-openapi.js | ||
| 79 | -``` | ||
| 80 | - | ||
| 81 | -#### 方式 3: 仅从 OpenAPI 生成代码 | ||
| 82 | - | ||
| 83 | -```bash | ||
| 84 | -pnpm api:generate | ||
| 85 | -``` | ||
| 86 | - | ||
| 87 | -## 📂 项目结构 | ||
| 88 | - | ||
| 89 | -``` | ||
| 90 | -manulife-weapp/ | ||
| 91 | -├── .env.apifox # Apifox 凭证配置(不提交到 Git) | ||
| 92 | -├── docs/ | ||
| 93 | -│ └── api-specs/ # OpenAPI 文档目录 | ||
| 94 | -│ ├── user/ # 按模块分类 | ||
| 95 | -│ │ ├── get-userinfo.md | ||
| 96 | -│ │ └── post-login.md | ||
| 97 | -│ └── product/ | ||
| 98 | -│ └── get-list.md | ||
| 99 | -├── src/ | ||
| 100 | -│ └── api/ # 生成的 API 代码 | ||
| 101 | -│ ├── user.js # 用户模块 API | ||
| 102 | -│ └── product.js # 产品模块 API | ||
| 103 | -└── scripts/ | ||
| 104 | - ├── apifox-to-openapi.js # Apifox → OpenAPI 转换器 | ||
| 105 | - └── generateApiFromOpenAPI.js # OpenAPI → API 代码生成器 | ||
| 106 | -``` | ||
| 107 | - | ||
| 108 | -## 📝 生成的代码示例 | ||
| 109 | - | ||
| 110 | -### OpenAPI 文档(`docs/api-specs/user/get-userinfo.md`) | ||
| 111 | - | ||
| 112 | -```markdown | ||
| 113 | -# 获取用户信息 | ||
| 114 | - | ||
| 115 | -获取当前登录用户的详细信息 | ||
| 116 | - | ||
| 117 | -## 接口信息 | ||
| 118 | - | ||
| 119 | -- **方法**: GET | ||
| 120 | -- **路径**: /srv/?a=get_userinfo | ||
| 121 | -- **标签**: user | ||
| 122 | - | ||
| 123 | -## OpenAPI 规范 | ||
| 124 | - | ||
| 125 | -\`\`\`yaml | ||
| 126 | -openapi: 3.0.0 | ||
| 127 | -info: | ||
| 128 | - title: 获取用户信息 | ||
| 129 | - description: 获取当前登录用户的详细信息 | ||
| 130 | - version: '1.0.0' | ||
| 131 | -paths: | ||
| 132 | - /srv/: | ||
| 133 | - get: | ||
| 134 | - summary: 获取用户信息 | ||
| 135 | - description: 获取当前登录用户的详细信息 | ||
| 136 | - parameters: | ||
| 137 | - - name: a | ||
| 138 | - in: query | ||
| 139 | - description: 接口动作 | ||
| 140 | - required: true | ||
| 141 | - schema: | ||
| 142 | - type: string | ||
| 143 | - example: get_userinfo | ||
| 144 | - responses: | ||
| 145 | - '200': | ||
| 146 | - description: 成功 | ||
| 147 | - content: | ||
| 148 | - application/json: | ||
| 149 | - schema: | ||
| 150 | - type: object | ||
| 151 | - properties: | ||
| 152 | - code: | ||
| 153 | - type: number | ||
| 154 | - description: 状态码 | ||
| 155 | - msg: | ||
| 156 | - type: string | ||
| 157 | - description: 消息 | ||
| 158 | - data: | ||
| 159 | - type: object | ||
| 160 | - properties: | ||
| 161 | - userId: | ||
| 162 | - type: string | ||
| 163 | - description: 用户 ID | ||
| 164 | - userName: | ||
| 165 | - type: string | ||
| 166 | - description: 用户名 | ||
| 167 | -\`\`\` | ||
| 168 | -``` | ||
| 169 | - | ||
| 170 | -### API 代码(`src/api/user.js`) | ||
| 171 | - | ||
| 172 | -```javascript | ||
| 173 | -/** | ||
| 174 | - * @description: 获取用户信息 | ||
| 175 | - * @param {Object} params 请求参数 | ||
| 176 | - * @returns {Promise<{ | ||
| 177 | - * code: number; // 状态码 | ||
| 178 | - * msg: string; // 消息 | ||
| 179 | - * data: { | ||
| 180 | - * userId: string; // 用户 ID | ||
| 181 | - * userName: string; // 用户名 | ||
| 182 | - * }; | ||
| 183 | - * }>} | ||
| 184 | - */ | ||
| 185 | -export const getUserinfoAPI = (params) => fn(fetch.get(Api.GetUserinfo, params)); | ||
| 186 | -``` | ||
| 187 | - | ||
| 188 | -## 💡 在组件中使用 | ||
| 189 | - | ||
| 190 | -### 1. 导入 API | ||
| 191 | - | ||
| 192 | -```javascript | ||
| 193 | -import { getUserinfoAPI, postLoginAPI } from '@/api/user' | ||
| 194 | -import { getProductListAPI } from '@/api/product' | ||
| 195 | -``` | ||
| 196 | - | ||
| 197 | -### 2. 使用 API | ||
| 198 | - | ||
| 199 | -```vue | ||
| 200 | -<script setup> | ||
| 201 | -import { ref, onMounted } from 'vue' | ||
| 202 | -import { getUserinfoAPI } from '@/api/user' | ||
| 203 | - | ||
| 204 | -const userInfo = ref(null) | ||
| 205 | -const loading = ref(false) | ||
| 206 | - | ||
| 207 | -// 获取用户信息 | ||
| 208 | -const fetchUserInfo = async () => { | ||
| 209 | - try { | ||
| 210 | - loading.value = true | ||
| 211 | - const res = await getUserinfoAPI({ userId: '123' }) | ||
| 212 | - | ||
| 213 | - if (res.code === 1) { | ||
| 214 | - userInfo.value = res.data | ||
| 215 | - } else { | ||
| 216 | - console.error('获取用户信息失败:', res.msg) | ||
| 217 | - } | ||
| 218 | - } catch (err) { | ||
| 219 | - console.error('请求失败:', err) | ||
| 220 | - } finally { | ||
| 221 | - loading.value = false | ||
| 222 | - } | ||
| 223 | -} | ||
| 224 | - | ||
| 225 | -onMounted(() => { | ||
| 226 | - fetchUserInfo() | ||
| 227 | -}) | ||
| 228 | -</script> | ||
| 229 | - | ||
| 230 | -<template> | ||
| 231 | - <div v-if="loading">加载中...</div> | ||
| 232 | - <div v-else-if="userInfo"> | ||
| 233 | - <p>用户名: {{ userInfo.userName }}</p> | ||
| 234 | - </div> | ||
| 235 | -</template> | ||
| 236 | -``` | ||
| 237 | - | ||
| 238 | -## 🔧 高级配置 | ||
| 239 | - | ||
| 240 | -### 1. 自定义输出目录 | ||
| 241 | - | ||
| 242 | -修改 `scripts/apifox-to-openapi.js` 中的配置: | ||
| 243 | - | ||
| 244 | -```javascript | ||
| 245 | -const CONFIG = { | ||
| 246 | - outputDir: path.join(__dirname, '../docs/api-specs'), | ||
| 247 | - autoGenerate: true // 是否自动运行 API 代码生成 | ||
| 248 | -}; | ||
| 249 | -``` | ||
| 250 | - | ||
| 251 | -### 2. 按需同步 | ||
| 252 | - | ||
| 253 | -如果只想同步特定的接口标签,可以修改 `fetchApis()` 函数添加过滤逻辑: | ||
| 254 | - | ||
| 255 | -```javascript | ||
| 256 | -// 只获取特定标签的接口 | ||
| 257 | -const tagsToSync = ['user', 'product']; | ||
| 258 | -const filteredApis = apis.filter(api => | ||
| 259 | - api.attributes?.tags?.some(tag => tagsToSync.includes(tag)) | ||
| 260 | -); | ||
| 261 | -``` | ||
| 262 | - | ||
| 263 | -### 3. 禁用自动代码生成 | ||
| 264 | - | ||
| 265 | -在 `.env.apifox` 中添加: | ||
| 266 | - | ||
| 267 | -```bash | ||
| 268 | -VITE_APIFOX_AUTO_GENERATE=false | ||
| 269 | -``` | ||
| 270 | - | ||
| 271 | -## 📊 变更检测 | ||
| 272 | - | ||
| 273 | -系统会自动检测 API 变更并显示差异报告: | ||
| 274 | - | ||
| 275 | -```bash | ||
| 276 | -pnpm api:sync | ||
| 277 | - | ||
| 278 | -# 输出示例: | ||
| 279 | -🔍 开始检测 API 变更... | ||
| 280 | - | ||
| 281 | -📦 新增模块: product | ||
| 282 | - | ||
| 283 | -📝 模块: user | ||
| 284 | - ✨ 新增接口: post-resetPassword | ||
| 285 | - 重置用户密码 | ||
| 286 | - | ||
| 287 | -✅ 检测到 2 个变更 | ||
| 288 | -``` | ||
| 289 | - | ||
| 290 | -## 🛡️ 安全最佳实践 | ||
| 291 | - | ||
| 292 | -### 1. 保护敏感信息 | ||
| 293 | - | ||
| 294 | -- ✅ 将 `.env.apifox` 添加到 `.gitignore` | ||
| 295 | -- ✅ 不要在代码中硬编码 API Token | ||
| 296 | -- ✅ 定期轮换 API Token | ||
| 297 | - | ||
| 298 | -### 2. 访问控制 | ||
| 299 | - | ||
| 300 | -在 Apifox 中: | ||
| 301 | -- 设置合适的权限(只读、编辑、管理) | ||
| 302 | -- 为不同环境创建不同的 Token | ||
| 303 | -- 记录 Token 使用情况 | ||
| 304 | - | ||
| 305 | -## 🐛 常见问题 | ||
| 306 | - | ||
| 307 | -### Q1: 提示"未找到 .env.apifox 文件" | ||
| 308 | - | ||
| 309 | -**解决方案**: 创建 `.env.apifox` 文件并填写凭证 | ||
| 310 | - | ||
| 311 | -```bash | ||
| 312 | -touch .env.apifox | ||
| 313 | -``` | ||
| 314 | - | ||
| 315 | -### Q2: 提示"获取接口失败: HTTP 401" | ||
| 316 | - | ||
| 317 | -**原因**: API Token 无效或已过期 | ||
| 318 | - | ||
| 319 | -**解决方案**: | ||
| 320 | -1. 检查 Token 是否正确 | ||
| 321 | -2. 在 Apifox 中重新生成 Token | ||
| 322 | -3. 更新 `.env.apifox` 文件 | ||
| 323 | - | ||
| 324 | -### Q3: 提示"项目不存在" | ||
| 325 | - | ||
| 326 | -**原因**: 项目 ID 错误或无权限访问 | ||
| 327 | - | ||
| 328 | -**解决方案**: | ||
| 329 | -1. 检查项目 ID 是否正确 | ||
| 330 | -2. 确认账号有该项目的访问权限 | ||
| 331 | -3. 在 Apifox 中检查项目设置 | ||
| 332 | - | ||
| 333 | -### Q4: 生成的 API 代码无法导入 | ||
| 334 | - | ||
| 335 | -**原因**: 路径别名配置问题 | ||
| 336 | - | ||
| 337 | -**解决方案**: | ||
| 338 | -1. 检查 `config/index.js` 中的路径别名配置 | ||
| 339 | -2. 确认 `@/api` 指向正确的目录 | ||
| 340 | -3. 重启开发服务器 | ||
| 341 | - | ||
| 342 | -### Q5: 如何只同步部分接口? | ||
| 343 | - | ||
| 344 | -**方案 1**: 在 Apifox 中使用标签分类接口,然后修改脚本过滤特定标签 | ||
| 345 | - | ||
| 346 | -**方案 2**: 手动管理 `docs/api-specs/` 目录,只保留需要的接口文档 | ||
| 347 | - | ||
| 348 | -## 📚 参考资料 | ||
| 349 | - | ||
| 350 | -- [Apifox 官方文档](https://apifox.com/docs/) | ||
| 351 | -- [OpenAPI 3.0 规范](https://swagger.io/specification/) | ||
| 352 | -- [项目 API 管理最佳实践](./api-best-practices.md) | ||
| 353 | - | ||
| 354 | -## 🔄 更新日志 | ||
| 355 | - | ||
| 356 | -### v1.0.0 (2026-01-30) | ||
| 357 | - | ||
| 358 | -- ✨ 初始版本 | ||
| 359 | -- ✅ 支持 Apifox API Token 认证 | ||
| 360 | -- ✅ 自动转换为 OpenAPI 3.0 格式 | ||
| 361 | -- ✅ 集成现有代码生成系统 | ||
| 362 | -- ✅ 支持变更检测 | ||
| 363 | - | ||
| 364 | -## 💬 反馈与支持 | ||
| 365 | - | ||
| 366 | -如有问题或建议,请: | ||
| 367 | -1. 查看本文档的"常见问题"部分 | ||
| 368 | -2. 联系项目负责人 | ||
| 369 | -3. 在项目 Issues 中提问 | ||
| 370 | - | ||
| 371 | ---- | ||
| 372 | - | ||
| 373 | -**最后更新**: 2026-01-30 | ||
| 374 | -**维护者**: Manulife WeApp Team |
docs/mcp/MCP 配置测试指南.md
deleted
100644 → 0
| 1 | -# Manulife WeApp - Apifox MCP 配置测试指南 | ||
| 2 | - | ||
| 3 | -## ✅ 配置状态 | ||
| 4 | - | ||
| 5 | -### 已完成 | ||
| 6 | - | ||
| 7 | -1. **项目级 MCP 配置已创建**:`.claude/settings.json` | ||
| 8 | -2. **MCP 服务器名称**:`manulife_API_文档` | ||
| 9 | -3. **Token 验证通过**:APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc | ||
| 10 | -4. **Project ID**:6084040 (当前复用 mlaj 项目) | ||
| 11 | - | ||
| 12 | -> **注意**:当前配置使用 mlaj 项目的 Apifox。如果 manulife-weapp 有独立的 Apifox 项目,需要更新 Project ID 和 Token。 | ||
| 13 | - | ||
| 14 | ---- | ||
| 15 | - | ||
| 16 | -## 🧪 测试方法 | ||
| 17 | - | ||
| 18 | -### 方法 1:重启 Claude Code 并直接使用(最简单) | ||
| 19 | - | ||
| 20 | -**步骤**: | ||
| 21 | - | ||
| 22 | -1. **完全退出 Claude Code**(确保重启) | ||
| 23 | -2. **重新启动 Claude Code** | ||
| 24 | -3. **打开 manulife-weapp 项目** | ||
| 25 | -4. **直接提问**: | ||
| 26 | - | ||
| 27 | -``` | ||
| 28 | -"列出 manulife 项目中所有的 API 接口" | ||
| 29 | -``` | ||
| 30 | - | ||
| 31 | -如果 MCP 配置正确,Claude Code 会: | ||
| 32 | - | ||
| 33 | -- 自动连接到 Apifox MCP 服务器 | ||
| 34 | -- 获取项目中的 API 列表 | ||
| 35 | -- 以结构化的方式展示给你 | ||
| 36 | - | ||
| 37 | -**其他测试命令**: | ||
| 38 | - | ||
| 39 | -``` | ||
| 40 | -# 搜索特定接口 | ||
| 41 | -"搜索 manulife 项目中与用户相关的 API" | ||
| 42 | - | ||
| 43 | -# 查看接口详情 | ||
| 44 | -"获取用户信息接口的完整信息" | ||
| 45 | - | ||
| 46 | -# 生成 API 代码 | ||
| 47 | -"基于用户登录接口,生成前端 API 调用代码" | ||
| 48 | -``` | ||
| 49 | - | ||
| 50 | ---- | ||
| 51 | - | ||
| 52 | -### 方法 2:查看 MCP 工具列表 | ||
| 53 | - | ||
| 54 | -在重启 Claude Code 后,你可以在对话中问: | ||
| 55 | - | ||
| 56 | -``` | ||
| 57 | -"列出当前可用的所有 MCP 工具" | ||
| 58 | -``` | ||
| 59 | - | ||
| 60 | -应该能看到类似这样的工具: | ||
| 61 | - | ||
| 62 | -- `mcp__manulife_api_文档__list_apis` - 列出所有 API | ||
| 63 | -- `mcp__manulife_api_文档__get_api_detail` - 获取 API 详情 | ||
| 64 | -- `mcp__manulife_api_文档__search_apis` - 搜索 API | ||
| 65 | -- `mcp__manulife_api_文档__get_project_info` - 项目信息 | ||
| 66 | - | ||
| 67 | ---- | ||
| 68 | - | ||
| 69 | -### 方法 3:创建测试脚本 | ||
| 70 | - | ||
| 71 | -创建 `test-mcp-connection.sh`: | ||
| 72 | - | ||
| 73 | -```bash | ||
| 74 | -#!/bin/bash | ||
| 75 | - | ||
| 76 | -# 检查 MCP 服务器是否能正常启动 | ||
| 77 | - | ||
| 78 | -echo "🔍 测试 Apifox MCP 服务器连接..." | ||
| 79 | -echo "" | ||
| 80 | - | ||
| 81 | -# 设置环境变量 | ||
| 82 | -export APIFOX_ACCESS_TOKEN="APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc" | ||
| 83 | - | ||
| 84 | -# 测试命令 | ||
| 85 | -echo "✅ Token 格式: 正确" | ||
| 86 | -echo "✅ Project ID: 6084040" | ||
| 87 | -echo "✅ MCP 配置文件: .claude/settings.json" | ||
| 88 | - | ||
| 89 | -echo "" | ||
| 90 | -echo "📝 配置内容:" | ||
| 91 | -cat .claude/settings.json | ||
| 92 | - | ||
| 93 | -echo "" | ||
| 94 | -echo "💡 下一步:" | ||
| 95 | -echo " 1. 重启 Claude Code" | ||
| 96 | -echo " 2. 在对话中问:'列出 manulife 项目所有的 API'" | ||
| 97 | -echo " 3. 如果能看到 API 列表,说明配置成功" | ||
| 98 | -``` | ||
| 99 | - | ||
| 100 | -运行测试: | ||
| 101 | - | ||
| 102 | -```bash | ||
| 103 | -chmod +x test-mcp-connection.sh | ||
| 104 | -./test-mcp-connection.sh | ||
| 105 | -``` | ||
| 106 | - | ||
| 107 | ---- | ||
| 108 | - | ||
| 109 | -## 🎯 预期效果 | ||
| 110 | - | ||
| 111 | -### 如果配置成功 | ||
| 112 | - | ||
| 113 | -当你问 **"列出 manulife 项目所有的 API"** 时,Claude Code 应该能: | ||
| 114 | - | ||
| 115 | -1. **连接到 Apifox**:通过 MCP 服务器 | ||
| 116 | -2. **获取 API 列表**:从项目 ID 6084040 | ||
| 117 | -3. **结构化展示**:按模块或分类显示 | ||
| 118 | - | ||
| 119 | -**示例输出**: | ||
| 120 | - | ||
| 121 | -``` | ||
| 122 | -我找到了 manulife 项目中的以下 API 接口: | ||
| 123 | - | ||
| 124 | -## 用户模块 | ||
| 125 | -- POST /srv/?a=openid_wxapp - 微信登录 | ||
| 126 | -- POST /srv/?a=get_user_info - 获取用户信息 | ||
| 127 | -- POST /srv/?a=edit_user_info - 编辑用户信息 | ||
| 128 | - | ||
| 129 | -## 产品模块 | ||
| 130 | -- POST /srv/?a=product_list - 获取产品列表 | ||
| 131 | -- POST /srv/?a=product_detail - 获取产品详情 | ||
| 132 | - | ||
| 133 | -## 知识库模块 | ||
| 134 | -- POST /srv/?a=knowledge_list - 获取知识列表 | ||
| 135 | -- POST /srv/?a=knowledge_detail - 获取知识详情 | ||
| 136 | - | ||
| 137 | -... (更多接口) | ||
| 138 | - | ||
| 139 | -需要查看某个接口的详细信息吗? | ||
| 140 | -``` | ||
| 141 | - | ||
| 142 | ---- | ||
| 143 | - | ||
| 144 | -## 🔧 使用独立的 Apifox 项目(可选) | ||
| 145 | - | ||
| 146 | -如果 manulife-weapp 有独立的 Apifox 项目: | ||
| 147 | - | ||
| 148 | -### 步骤 1:获取 Project ID 和 Token | ||
| 149 | - | ||
| 150 | -1. 登录 [Apifox](https://app.apifox.com) | ||
| 151 | -2. 打开 manulife-weapp 项目 | ||
| 152 | -3. 从 URL 中获取 Project ID:`https://app.apifox.com/web/project/{PROJECT_ID}/...` | ||
| 153 | -4. 生成 Access Token:设置 → API Tokens → 新建 Token | ||
| 154 | - | ||
| 155 | -### 步骤 2:更新配置文件 | ||
| 156 | - | ||
| 157 | -编辑 `.claude/settings.json`: | ||
| 158 | - | ||
| 159 | -```json | ||
| 160 | -{ | ||
| 161 | - "mcpServers": { | ||
| 162 | - "manulife_API_文档": { | ||
| 163 | - "command": "npx", | ||
| 164 | - "args": [ | ||
| 165 | - "-y", | ||
| 166 | - "apifox-mcp-server@latest", | ||
| 167 | - "--project-id=YOUR_PROJECT_ID" | ||
| 168 | - ], | ||
| 169 | - "env": { | ||
| 170 | - "APIFOX_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN" | ||
| 171 | - } | ||
| 172 | - } | ||
| 173 | - } | ||
| 174 | -} | ||
| 175 | -``` | ||
| 176 | - | ||
| 177 | -### 步骤 3:重启 Claude Code | ||
| 178 | - | ||
| 179 | -1. 完全退出 Claude Code | ||
| 180 | -2. 重新启动 | ||
| 181 | -3. 测试连接 | ||
| 182 | - | ||
| 183 | ---- | ||
| 184 | - | ||
| 185 | -## 🐛 故障排查 | ||
| 186 | - | ||
| 187 | -### 问题 1:看不到 MCP 工具 | ||
| 188 | - | ||
| 189 | -**检查步骤**: | ||
| 190 | - | ||
| 191 | -1. 确认配置文件存在: | ||
| 192 | - | ||
| 193 | - ```bash | ||
| 194 | - cat .claude/settings.json | ||
| 195 | - ``` | ||
| 196 | - | ||
| 197 | -2. 完全重启 Claude Code(不是重新加载) | ||
| 198 | - | ||
| 199 | -3. 查看日志: | ||
| 200 | - ```bash | ||
| 201 | - tail -50 ~/Library/Logs/Claude/claude-desktop.log | grep -i mcp | ||
| 202 | - ``` | ||
| 203 | - | ||
| 204 | -### 问题 2:连接超时或失败 | ||
| 205 | - | ||
| 206 | -**检查步骤**: | ||
| 207 | - | ||
| 208 | -1. 测试网络连接: | ||
| 209 | - | ||
| 210 | - ```bash | ||
| 211 | - curl -I https://apifox.com | ||
| 212 | - ``` | ||
| 213 | - | ||
| 214 | -2. 验证 Token: | ||
| 215 | - | ||
| 216 | - ```bash | ||
| 217 | - # 在浏览器中访问 Apifox,确认 token 有效 | ||
| 218 | - ``` | ||
| 219 | - | ||
| 220 | -3. 手动测试 MCP 服务器: | ||
| 221 | - ```bash | ||
| 222 | - APIFOX_ACCESS_TOKEN="your_token" \ | ||
| 223 | - npx -y apifox-mcp-server@latest --project-id=6084040 | ||
| 224 | - ``` | ||
| 225 | - | ||
| 226 | -### 问题 3:工具调用失败 | ||
| 227 | - | ||
| 228 | -**可能原因**: | ||
| 229 | - | ||
| 230 | -- Project ID 不匹配 | ||
| 231 | -- Token 权限不足 | ||
| 232 | -- 项目在 Apifox 中被删除或移动 | ||
| 233 | - | ||
| 234 | -**解决**: | ||
| 235 | - | ||
| 236 | -1. 登录 Apifox 确认项目存在 | ||
| 237 | -2. 确认 Token 有该项目的访问权限 | ||
| 238 | -3. 重新获取正确的 Project ID | ||
| 239 | - | ||
| 240 | ---- | ||
| 241 | - | ||
| 242 | -## 📚 Apifox MCP 服务器功能 | ||
| 243 | - | ||
| 244 | -根据 Apifox MCP 服务器的标准功能,应该支持: | ||
| 245 | - | ||
| 246 | -### 📖 查看功能 | ||
| 247 | - | ||
| 248 | -- **列出所有 API**:获取项目中的接口列表 | ||
| 249 | -- **获取 API 详情**:查看单个接口的完整信息 | ||
| 250 | -- **搜索 API**:按名称或路径搜索接口 | ||
| 251 | -- **获取项目信息**:项目基本信息 | ||
| 252 | - | ||
| 253 | -### 🔧 集成功能(可能) | ||
| 254 | - | ||
| 255 | -- **发送测试请求**:直接调用 API 测试 | ||
| 256 | -- **生成代码**:自动生成前端 API 调用代码 | ||
| 257 | -- **导出文档**:导出为 Markdown 或其他格式 | ||
| 258 | - | ||
| 259 | ---- | ||
| 260 | - | ||
| 261 | -## 🚀 高级用法 | ||
| 262 | - | ||
| 263 | -### 1. 自动生成 API 代码 | ||
| 264 | - | ||
| 265 | -配置成功后,可以快速生成前端 API 代码: | ||
| 266 | - | ||
| 267 | -``` | ||
| 268 | -"基于 manulife 项目的用户登录接口, | ||
| 269 | -生成 src/api/user.js 文件, | ||
| 270 | -使用 axios,遵循项目规范" | ||
| 271 | -``` | ||
| 272 | - | ||
| 273 | -### 2. 批量生成接口文档 | ||
| 274 | - | ||
| 275 | -``` | ||
| 276 | -"为 manulife 项目生成完整的 API 文档, | ||
| 277 | -包括所有接口的请求参数和响应格式" | ||
| 278 | -``` | ||
| 279 | - | ||
| 280 | -### 3. 接口变更检测 | ||
| 281 | - | ||
| 282 | -``` | ||
| 283 | -"对比 manulife 项目的接口变更, | ||
| 284 | -列出新增和修改的接口" | ||
| 285 | -``` | ||
| 286 | - | ||
| 287 | ---- | ||
| 288 | - | ||
| 289 | -## 📝 配置文件说明 | ||
| 290 | - | ||
| 291 | -### 项目级配置:`.claude/settings.json` | ||
| 292 | - | ||
| 293 | -```json | ||
| 294 | -{ | ||
| 295 | - "mcpServers": { | ||
| 296 | - "manulife_API_文档": { | ||
| 297 | - "command": "npx", | ||
| 298 | - "args": ["-y", "apifox-mcp-server@latest", "--project-id=6084040"], | ||
| 299 | - "env": { | ||
| 300 | - "APIFOX_ACCESS_TOKEN": "APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc" | ||
| 301 | - } | ||
| 302 | - } | ||
| 303 | - } | ||
| 304 | -} | ||
| 305 | -``` | ||
| 306 | - | ||
| 307 | -### 环境变量 | ||
| 308 | - | ||
| 309 | -- `APIFOX_ACCESS_TOKEN`: Apifox 访问令牌 | ||
| 310 | -- `PROJECT_ID`: 项目 ID (当前为 6084040) | ||
| 311 | - | ||
| 312 | ---- | ||
| 313 | - | ||
| 314 | -## 🎉 成功标志 | ||
| 315 | - | ||
| 316 | -当你看到以下情况时,说明配置成功: | ||
| 317 | - | ||
| 318 | -1. ✅ Claude Code 能列出 manulife 项目的 API 接口 | ||
| 319 | -2. ✅ 能获取单个接口的详细信息 | ||
| 320 | -3. ✅ 能搜索和筛选接口 | ||
| 321 | -4. ✅ 能基于接口文档生成代码 | ||
| 322 | - | ||
| 323 | ---- | ||
| 324 | - | ||
| 325 | -**最后更新**: 2026-01-30 | ||
| 326 | -**MCP 服务器**: apifox-mcp-server@latest | ||
| 327 | -**项目 ID**: 6084040 (复用 mlaj 项目) | ||
| 328 | -**配置状态**: ✅ 完成,等待重启验证 |
docs/mcp/如何切换到独立 Apifox 项目.md
deleted
100644 → 0
| 1 | -# 如何切换到独立的 Apifox 项目 | ||
| 2 | - | ||
| 3 | -## 当前状态 | ||
| 4 | - | ||
| 5 | -✅ **MCP 服务器已配置**,当前复用 **mlaj 项目的 Apifox**(Project ID: 6084040) | ||
| 6 | - | ||
| 7 | ---- | ||
| 8 | - | ||
| 9 | -## 📝 将来切换到独立项目时,修改以下位置 | ||
| 10 | - | ||
| 11 | -### 位置 1:项目级配置(主要) | ||
| 12 | - | ||
| 13 | -**文件路径**:`.claude/settings.json` | ||
| 14 | - | ||
| 15 | -**修改内容**: | ||
| 16 | - | ||
| 17 | -```json | ||
| 18 | -{ | ||
| 19 | - "mcpServers": { | ||
| 20 | - "manulife_API_文档": { | ||
| 21 | - "command": "npx", | ||
| 22 | - "args": [ | ||
| 23 | - "-y", | ||
| 24 | - "apifox-mcp-server@latest", | ||
| 25 | - "--project-id=这里填写新的PROJECT_ID" // ← 改这里 | ||
| 26 | - ], | ||
| 27 | - "env": { | ||
| 28 | - "APIFOX_ACCESS_TOKEN": "这里填写新的ACCESS_TOKEN" // ← 改这里 | ||
| 29 | - } | ||
| 30 | - } | ||
| 31 | - } | ||
| 32 | -} | ||
| 33 | -``` | ||
| 34 | - | ||
| 35 | -### 位置 2:本地权限配置(次要) | ||
| 36 | - | ||
| 37 | -**文件路径**:`.claude/settings.local.json` | ||
| 38 | - | ||
| 39 | -**修改内容**: | ||
| 40 | - | ||
| 41 | -找到这一行: | ||
| 42 | -```json | ||
| 43 | -"Bash(APIFOX_ACCESS_TOKEN=\"旧的TOKEN\" npx -y apifox-mcp-server@latest --project-id=旧的PROJECT_ID:*)", | ||
| 44 | -``` | ||
| 45 | - | ||
| 46 | -替换为: | ||
| 47 | -```json | ||
| 48 | -"Bash(APIFOX_ACCESS_TOKEN=\"新的TOKEN\" npx -y apifox-mcp-server@latest --project-id=新的PROJECT_ID:*)", | ||
| 49 | -``` | ||
| 50 | - | ||
| 51 | ---- | ||
| 52 | - | ||
| 53 | -## 🔑 如何获取新的 Project ID 和 Token | ||
| 54 | - | ||
| 55 | -### 步骤 1:获取 Project ID | ||
| 56 | - | ||
| 57 | -1. 登录 [Apifox](https://app.apifox.com) | ||
| 58 | -2. 打开 manulife-weapp 项目 | ||
| 59 | -3. 从 URL 中复制 Project ID: | ||
| 60 | - | ||
| 61 | - ``` | ||
| 62 | - https://app.apifox.com/web/project/{PROJECT_ID}/apis/api-xxxxx | ||
| 63 | - ↑ 这里就是 Project ID | ||
| 64 | - ``` | ||
| 65 | - | ||
| 66 | -### 步骤 2:生成 Access Token | ||
| 67 | - | ||
| 68 | -1. 在 Apifox 中,点击 **设置** → **API Tokens** | ||
| 69 | -2. 点击 **新建 Token** | ||
| 70 | -3. 复制生成的 Token(格式类似:`APS-xxxxx`) | ||
| 71 | - | ||
| 72 | ---- | ||
| 73 | - | ||
| 74 | -## ✅ 修改后记得 | ||
| 75 | - | ||
| 76 | -1. **保存文件** | ||
| 77 | -2. **完全退出 Claude Code** | ||
| 78 | -3. **重新启动 Claude Code** | ||
| 79 | -4. **测试连接**: | ||
| 80 | - ``` | ||
| 81 | - "列出 manulife 项目中所有的 API 接口" | ||
| 82 | - ``` | ||
| 83 | - | ||
| 84 | ---- | ||
| 85 | - | ||
| 86 | -**快速参考**: | ||
| 87 | -- 主配置文件:`.claude/settings.json`(第 8 行和第 11 行) | ||
| 88 | -- 权限文件:`.claude/settings.local.json`(第 49 行) |
docs/reports/Apifox 设置总结.md
deleted
100644 → 0
| 1 | -# 🎉 Apifox 集成设置完成 | ||
| 2 | - | ||
| 3 | -## ✅ 已完成的配置 | ||
| 4 | - | ||
| 5 | -### 1. 核心文件 | ||
| 6 | - | ||
| 7 | -| 文件 | 说明 | | ||
| 8 | -|------|------| | ||
| 9 | -| `.env.apifox` | Apifox 凭证配置文件(需要您填写) | | ||
| 10 | -| `.env.apifox.example` | 配置文件模板 | | ||
| 11 | -| `scripts/apifox-to-openapi.js` | Apifox → OpenAPI 转换工具 | | ||
| 12 | -| `scripts/test-apifox-connection.js` | Apifox 连接测试工具 | | ||
| 13 | -| `scripts/apifox-sync.js` | 备用的独立同步工具 | | ||
| 14 | - | ||
| 15 | -### 2. 文档文件 | ||
| 16 | - | ||
| 17 | -| 文件 | 说明 | | ||
| 18 | -|------|------| | ||
| 19 | -| `QUICKSTART_APIFOX.md` | 快速开始指南 | | ||
| 20 | -| `docs/apifox-integration-guide.md` | 完整集成指南 | | ||
| 21 | - | ||
| 22 | -### 3. 配置更新 | ||
| 23 | - | ||
| 24 | -| 文件 | 更新内容 | | ||
| 25 | -|------|----------| | ||
| 26 | -| `package.json` | 添加了 `api:sync` 和 `api:test` 命令 | | ||
| 27 | -| `.gitignore` | 添加了 `.env.apifox` 以保护敏感信息 | | ||
| 28 | - | ||
| 29 | -## 🚀 开始使用 | ||
| 30 | - | ||
| 31 | -### 步骤 1:配置 Apifox 凭证 | ||
| 32 | - | ||
| 33 | -```bash | ||
| 34 | -# 1. 复制示例配置 | ||
| 35 | -cp .env.apifox.example .env.apifox | ||
| 36 | - | ||
| 37 | -# 2. 编辑 .env.apifox,填写您的 Apifox 信息 | ||
| 38 | -# VITE_APIFOX_TOKEN=aps-your_token_here | ||
| 39 | -# VITE_APIFOX_PROJECT_ID=your_project_id_here | ||
| 40 | -``` | ||
| 41 | - | ||
| 42 | -### 步骤 2:测试连接 | ||
| 43 | - | ||
| 44 | -```bash | ||
| 45 | -# 测试 Apifox 连接是否正常 | ||
| 46 | -pnpm api:test | ||
| 47 | -``` | ||
| 48 | - | ||
| 49 | -这个命令会: | ||
| 50 | -- ✅ 验证配置文件格式 | ||
| 51 | -- ✅ 测试 API Token 是否有效 | ||
| 52 | -- ✅ 显示项目基本信息 | ||
| 53 | -- ✅ 列出前 10 个接口 | ||
| 54 | - | ||
| 55 | -### 步骤 3:同步 API | ||
| 56 | - | ||
| 57 | -```bash | ||
| 58 | -# 从 Apifox 同步所有接口 | ||
| 59 | -pnpm api:sync | ||
| 60 | -``` | ||
| 61 | - | ||
| 62 | -这个命令会: | ||
| 63 | -- ✅ 从 Apifox 获取所有接口数据 | ||
| 64 | -- ✅ 转换为 OpenAPI 3.0 格式 | ||
| 65 | -- ✅ 保存到 `docs/api-specs/` 目录 | ||
| 66 | -- ✅ 自动生成 API 代码到 `src/api/` 目录 | ||
| 67 | - | ||
| 68 | -## 📋 可用命令 | ||
| 69 | - | ||
| 70 | -| 命令 | 说明 | | ||
| 71 | -|------|------| | ||
| 72 | -| `pnpm api:test` | 测试 Apifox 连接 | | ||
| 73 | -| `pnpm api:sync` | 从 Apifox 同步 API(推荐) | | ||
| 74 | -| `pnpm api:generate` | 从 OpenAPI 文档生成代码 | | ||
| 75 | - | ||
| 76 | -## 💡 使用示例 | ||
| 77 | - | ||
| 78 | -### 在组件中使用生成的 API | ||
| 79 | - | ||
| 80 | -```javascript | ||
| 81 | -// 1. 导入生成的 API | ||
| 82 | -import { getUserInfoAPI } from '@/api/user' | ||
| 83 | -import { getProductListAPI } from '@/api/product' | ||
| 84 | - | ||
| 85 | -// 2. 调用 API | ||
| 86 | -const res = await getUserInfoAPI({ userId: '123' }) | ||
| 87 | - | ||
| 88 | -// 3. 检查返回值 | ||
| 89 | -if (res.code === 1) { | ||
| 90 | - console.log('成功:', res.data) | ||
| 91 | -} else { | ||
| 92 | - console.error('失败:', res.msg) | ||
| 93 | -} | ||
| 94 | -``` | ||
| 95 | - | ||
| 96 | -## 📂 生成的文件结构 | ||
| 97 | - | ||
| 98 | -``` | ||
| 99 | -docs/api-specs/ # OpenAPI 文档(Markdown) | ||
| 100 | -├── user/ # 用户模块 | ||
| 101 | -│ ├── get-userinfo.md | ||
| 102 | -│ └── post-login.md | ||
| 103 | -└── product/ # 产品模块 | ||
| 104 | - └── get-list.md | ||
| 105 | - | ||
| 106 | -src/api/ # 生成的 API 代码 | ||
| 107 | -├── user.js # 用户模块 API | ||
| 108 | -└── product.js # 产品模块 API | ||
| 109 | -``` | ||
| 110 | - | ||
| 111 | -## 🔍 故障排查 | ||
| 112 | - | ||
| 113 | -### 问题 1:找不到 .env.apifox 文件 | ||
| 114 | - | ||
| 115 | -**解决方案**: | ||
| 116 | -```bash | ||
| 117 | -cp .env.apifox.example .env.apifox | ||
| 118 | -``` | ||
| 119 | - | ||
| 120 | -### 问题 2:提示"HTTP 401" | ||
| 121 | - | ||
| 122 | -**原因**:API Token 无效 | ||
| 123 | - | ||
| 124 | -**解决方案**: | ||
| 125 | -1. 检查 Token 是否正确 | ||
| 126 | -2. 在 Apifox 中重新生成 Token | ||
| 127 | -3. 更新 `.env.apifox` 文件 | ||
| 128 | - | ||
| 129 | -### 问题 3:提示"项目不存在" | ||
| 130 | - | ||
| 131 | -**原因**:项目 ID 错误或无权限 | ||
| 132 | - | ||
| 133 | -**解决方案**: | ||
| 134 | -1. 检查项目 ID 是否正确 | ||
| 135 | -2. 确认账号有该项目的访问权限 | ||
| 136 | -3. 检查 Apifox 项目设置 | ||
| 137 | - | ||
| 138 | -## 📚 更多资源 | ||
| 139 | - | ||
| 140 | -- **快速开始**: [QUICKSTART_APIFOX.md](../QUICKSTART_APIFOX.md) | ||
| 141 | -- **完整指南**: [apifox-integration-guide.md](./apifox-integration-guide.md) | ||
| 142 | -- **Apifox 文档**: https://apifox.com/docs/ | ||
| 143 | - | ||
| 144 | -## 🛡️ 安全提醒 | ||
| 145 | - | ||
| 146 | -⚠️ **重要**: | ||
| 147 | -- `.env.apifox` 包含敏感信息,已被添加到 `.gitignore` | ||
| 148 | -- 请勿将 `.env.apifox` 提交到 Git | ||
| 149 | -- 定期轮换 API Token | ||
| 150 | -- 在 Apifox 中设置合适的权限 | ||
| 151 | - | ||
| 152 | -## 🎯 下一步 | ||
| 153 | - | ||
| 154 | -1. ✅ 配置 `.env.apifox` 文件 | ||
| 155 | -2. ✅ 运行 `pnpm api:test` 测试连接 | ||
| 156 | -3. ✅ 运行 `pnpm api:sync` 同步 API | ||
| 157 | -4. ✅ 在组件中使用生成的 API | ||
| 158 | - | ||
| 159 | ---- | ||
| 160 | - | ||
| 161 | -**需要帮助?** 查看 [完整集成指南](./apifox-integration-guide.md) 或运行 `pnpm api:test` 诊断问题 | ||
| 162 | - | ||
| 163 | -**最后更新**: 2026-01-30 |
test-apifox-skill.js
deleted
100644 → 0
| 1 | -#!/usr/bin/env node | ||
| 2 | - | ||
| 3 | -/** | ||
| 4 | - * 测试 Apifox Skill 连接 | ||
| 5 | - */ | ||
| 6 | - | ||
| 7 | -const path = require('path'); | ||
| 8 | -const ApifoxClient = require('/Users/huyirui/.claude/skills/apifox/apifox-client.js'); | ||
| 9 | - | ||
| 10 | -// 测试配置 | ||
| 11 | -const testConfig = { | ||
| 12 | - VITE_APIFOX_TOKEN: 'APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc', | ||
| 13 | - VITE_APIFOX_PROJECT_ID: '6084040', | ||
| 14 | - VITE_APIFOX_CACHE_TIME: 3600 | ||
| 15 | -}; | ||
| 16 | - | ||
| 17 | -console.log('🧪 Apifox Skill 连接测试'); | ||
| 18 | -console.log('='.repeat(50)); | ||
| 19 | -console.log(''); | ||
| 20 | - | ||
| 21 | -// 显示配置信息 | ||
| 22 | -console.log('📝 测试配置:'); | ||
| 23 | -console.log(` Token: ${testConfig.VITE_APIFOX_TOKEN.substring(0, 20)}...`); | ||
| 24 | -console.log(` 项目 ID: ${testConfig.VITE_APIFOX_PROJECT_ID}`); | ||
| 25 | -console.log(''); | ||
| 26 | - | ||
| 27 | -async function testConnection() { | ||
| 28 | - const client = new ApifoxClient(testConfig); | ||
| 29 | - | ||
| 30 | - try { | ||
| 31 | - // 测试 1: 获取项目信息 | ||
| 32 | - console.log('📊 测试 1/3: 获取项目信息...'); | ||
| 33 | - const project = await client.getProjectInfo(); | ||
| 34 | - | ||
| 35 | - console.log('✅ 项目信息获取成功'); | ||
| 36 | - console.log(` 项目名称: ${project.name || '未设置'}`); | ||
| 37 | - console.log(` 项目 ID: ${project.id}`); | ||
| 38 | - console.log(` 描述: ${project.description || '无'}`); | ||
| 39 | - console.log(''); | ||
| 40 | - | ||
| 41 | - // 测试 2: 获取接口列表 | ||
| 42 | - console.log('📋 测试 2/3: 获取接口列表...'); | ||
| 43 | - const apis = await client.listAllApis(); | ||
| 44 | - | ||
| 45 | - console.log(`✅ 接口列表获取成功,共 ${apis.length} 个接口`); | ||
| 46 | - console.log(''); | ||
| 47 | - | ||
| 48 | - // 测试 3: 显示前 5 个接口 | ||
| 49 | - console.log('🔍 测试 3/3: 显示前 5 个接口...'); | ||
| 50 | - const sampleApis = apis.slice(0, 5); | ||
| 51 | - | ||
| 52 | - sampleApis.forEach((api, index) => { | ||
| 53 | - const method = (api.attributes?.method || 'GET').toUpperCase(); | ||
| 54 | - const path = api.attributes?.path || '/'; | ||
| 55 | - const name = api.attributes?.name || '未命名'; | ||
| 56 | - | ||
| 57 | - console.log(` ${index + 1}. ${method} ${path}`); | ||
| 58 | - console.log(` ${name}`); | ||
| 59 | - }); | ||
| 60 | - | ||
| 61 | - if (apis.length > 5) { | ||
| 62 | - console.log(` ... 还有 ${apis.length - 5} 个接口`); | ||
| 63 | - } | ||
| 64 | - | ||
| 65 | - console.log(''); | ||
| 66 | - console.log('='.repeat(50)); | ||
| 67 | - console.log('✅ 所有测试通过!'); | ||
| 68 | - console.log(''); | ||
| 69 | - console.log('🎉 Token 和 Project ID 验证成功!'); | ||
| 70 | - console.log('💡 你现在可以使用 Apifox Skill 了'); | ||
| 71 | - | ||
| 72 | - } catch (error) { | ||
| 73 | - console.log(''); | ||
| 74 | - console.log('❌ 测试失败'); | ||
| 75 | - console.log(''); | ||
| 76 | - | ||
| 77 | - if (error.message.includes('401')) { | ||
| 78 | - console.log('错误原因: HTTP 401 - Token 无效或已过期'); | ||
| 79 | - console.log(''); | ||
| 80 | - console.log('解决方案:'); | ||
| 81 | - console.log(' 1. 检查 Token 是否正确'); | ||
| 82 | - console.log(' 2. 在 Apifox 中重新生成 Token'); | ||
| 83 | - console.log(' 3. 更新 .env.apifox 文件'); | ||
| 84 | - } else if (error.message.includes('403') || error.message.includes('404')) { | ||
| 85 | - console.log('错误原因: HTTP 403/404 - 项目不存在或无权限'); | ||
| 86 | - console.log(''); | ||
| 87 | - console.log('解决方案:'); | ||
| 88 | - console.log(' 1. 检查项目 ID 是否正确'); | ||
| 89 | - console.log(' 2. 确认账号有该项目的访问权限'); | ||
| 90 | - console.log(' 3. 在 Apifox 中检查项目设置'); | ||
| 91 | - } else { | ||
| 92 | - console.log('错误原因:', error.message); | ||
| 93 | - console.log(''); | ||
| 94 | - console.log('详细错误:'); | ||
| 95 | - console.error(error); | ||
| 96 | - } | ||
| 97 | - | ||
| 98 | - process.exit(1); | ||
| 99 | - } | ||
| 100 | -} | ||
| 101 | - | ||
| 102 | -// 运行测试 | ||
| 103 | -testConnection().catch(err => { | ||
| 104 | - console.error(''); | ||
| 105 | - console.error('❌ 测试失败:', err.message); | ||
| 106 | - console.error(''); | ||
| 107 | - process.exit(1); | ||
| 108 | -}); |
test-mcp-connection.sh
deleted
100755 → 0
| 1 | -#!/bin/bash | ||
| 2 | - | ||
| 3 | -# 测试 Apifox MCP 服务器连接 | ||
| 4 | - | ||
| 5 | -echo "🔍 测试 Apifox MCP 服务器连接..." | ||
| 6 | -echo "" | ||
| 7 | - | ||
| 8 | -# 设置环境变量 | ||
| 9 | -export APIFOX_ACCESS_TOKEN="APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc" | ||
| 10 | - | ||
| 11 | -# 测试命令 | ||
| 12 | -echo "✅ Token 格式: 正确" | ||
| 13 | -echo "✅ Project ID: 6084040" | ||
| 14 | -echo "✅ MCP 配置文件: .claude/settings.json" | ||
| 15 | - | ||
| 16 | -echo "" | ||
| 17 | -echo "📝 当前配置内容:" | ||
| 18 | -cat .claude/settings.json | ||
| 19 | - | ||
| 20 | -echo "" | ||
| 21 | -echo "📋 检查清单:" | ||
| 22 | -echo " ✓ Token 已更新为: APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc" | ||
| 23 | -echo " ✓ Project ID: 6084040 (mlaj 项目)" | ||
| 24 | -echo "" | ||
| 25 | - | ||
| 26 | -echo "💡 下一步:" | ||
| 27 | -echo " 1. ✅ 配置已更新" | ||
| 28 | -echo " 2. ⚠️ 需要重启 Claude Code 才能生效" | ||
| 29 | -echo " 3. 重启后可以在对话中问:'列出 manulife 项目所有的 API'" | ||
| 30 | -echo "" | ||
| 31 | - | ||
| 32 | -echo "🔧 手动测试 MCP 服务器(可选):" | ||
| 33 | -echo " 运行以下命令测试服务器是否能启动:" | ||
| 34 | -echo "" | ||
| 35 | -echo " APIFOX_ACCESS_TOKEN=\"APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc\" \\" | ||
| 36 | -echo " npx -y apifox-mcp-server@latest --project-id=6084040" | ||
| 37 | -echo "" |
-
Please register or login to post a comment