Apifox 集成指南.md 8.31 KB

Raw Blame History Permalink



Apifox API 集成指南


📖 概述

本项目集成了 Apifox API 管理系统，可以自动从 Apifox 获取接口数据并生成 API 代码。


🎯 功能特性


✅ 自动同步: 从 Apifox 获取所有接口数据
✅ OpenAPI 转换: 将 Apifox 数据转换为 OpenAPI 3.0 格式
✅ 代码生成: 自动生成 JavaScript API 接口代码
✅ 类型安全: 生成完整的 JSDoc 类型注释
✅ 变更检测: 自动检测 API 变更并显示差异
✅ Mock 数据: 支持生成 Mock 数据（可选）


🚀 快速开始


1. 获取 Apifox 凭证


1.1 获取 API Token


登录 Apifox

点击右上角头像 → 个人设置

选择 API Token → 新建 Token

输入 Token 名称（如"Manulife WeApp"）
复制生成的 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 文件：

VITE_APIFOX_TOKEN=aps-your_token_here
VITE_APIFOX_PROJECT_ID=your_project_id_here


2.2 填写实际凭证

# Apifox API Token
VITE_APIFOX_TOKEN=aps-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Apifox 项目 ID
VITE_APIFOX_PROJECT_ID=12345678


⚠️ 重要: 请勿将 .env.apifox 文件提交到 Git！


3. 同步 API


方式 1: 使用 pnpm 命令（推荐）

pnpm api:sync


这个命令会：


从 Apifox 获取所有接口数据
转换为 OpenAPI 3.0 格式
保存到 docs/api-specs/ 目录
自动运行 api:generate 生成 API 代码


方式 2: 仅生成 OpenAPI 文档

node scripts/apifox-to-openapi.js


方式 3: 仅从 OpenAPI 生成代码

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）

# 获取用户信息

获取当前登录用户的详细信息

## 接口信息

- **方法**: 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）

/**
 * @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

import { getUserinfoAPI, postLoginAPI } from '@/api/user'
import { getProductListAPI } from '@/api/product'


2. 使用 API

<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 中的配置：

const CONFIG = {
  outputDir: path.join(__dirname, '../docs/api-specs'),
  autoGenerate: true // 是否自动运行 API 代码生成
};


2. 按需同步

如果只想同步特定的接口标签，可以修改 fetchApis() 函数添加过滤逻辑：

// 只获取特定标签的接口
const tagsToSync = ['user', 'product'];
const filteredApis = apis.filter(api =>
  api.attributes?.tags?.some(tag => tagsToSync.includes(tag))
);


3. 禁用自动代码生成

在 .env.apifox 中添加：

VITE_APIFOX_AUTO_GENERATE=false


📊 变更检测

系统会自动检测 API 变更并显示差异报告：

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 文件并填写凭证

touch .env.apifox


Q2: 提示"获取接口失败: HTTP 401"

原因: API Token 无效或已过期

解决方案:


检查 Token 是否正确
在 Apifox 中重新生成 Token
更新 .env.apifox 文件


Q3: 提示"项目不存在"

原因: 项目 ID 错误或无权限访问

解决方案:


检查项目 ID 是否正确
确认账号有该项目的访问权限
在 Apifox 中检查项目设置


Q4: 生成的 API 代码无法导入

原因: 路径别名配置问题

解决方案:


检查 config/index.js 中的路径别名配置
确认 @/api 指向正确的目录
重启开发服务器


Q5: 如何只同步部分接口？

方案 1: 在 Apifox 中使用标签分类接口，然后修改脚本过滤特定标签

方案 2: 手动管理 docs/api-specs/ 目录，只保留需要的接口文档


📚 参考资料


Apifox 官方文档
OpenAPI 3.0 规范
项目 API 管理最佳实践


🔄 更新日志


v1.0.0 (2026-01-30)


✨ 初始版本
✅ 支持 Apifox API Token 认证
✅ 自动转换为 OpenAPI 3.0 格式
✅ 集成现有代码生成系统
✅ 支持变更检测


💬 反馈与支持

如有问题或建议，请：


查看本文档的"常见问题"部分
联系项目负责人
在项目 Issues 中提问


最后更新: 2026-01-30
维护者: Manulife WeApp Team