ABC Apifox Skill

本 skill 提供 ABC 医疗云 API 文档查询功能。

环境配置

必需的环境变量

# 设置 Apifox Access Token（必需）
export APIFOX_ACCESS_TOKEN="你的 Apifox Access Token"

# 设置项目 ID（可选，默认为 4105462）
export APIFOX_PROJECT_ID="4105462"

获取 Token：登录 Apifox > 账号设置 > API 访问令牌

依赖安装

pip3 install requests

首次使用：初始化缓存

首次使用前需要初始化缓存（只需执行一次），执行以下命令：

# 初始化环境（自动安装依赖、检查配置、下载缓存）
python3 scripts/apifox.py init

初始化过程会自动：

1. 检查并安装 Python 依赖（requests）
2. 运行环境检查（验证 APIFOX_ACCESS_TOKEN 配置）
3. 从 Apifox 下载最新 API 文档并构建缓存

缓存初始化后，后续查询直接从本地读取，无需重复初始化。如需更新缓存，可使用 refresh_oas 命令。

工作原理

缓存架构：按模块拆分的缓存结构

1. 智能拆分：接口按模块拆分，Schema 按首字母分组
2. 按需加载：查询时只加载相关模块文件
3. 缓存持久：缓存永久有效，需要手动刷新获取最新文档
4. 自动保护：查询时内部自动检查缓存状态

使用方式

python3 scripts/apifox.py <command> [参数]

所有命令默认返回 JSON 格式输出。

命令列表

接口查询

命令	说明
get_path	获取接口详情（自动推断模块）
get_schema	获取 Schema 定义
search_paths	搜索接口（关键词匹配）
list_modules	列出所有模块
get_module	获取模块的所有接口

文档管理

命令	说明
init	初始化环境（安装依赖、检查配置、下载缓存）
refresh_oas	刷新 OpenAPI 文档
status	查看缓存状态
clear_cache	清除本地缓存（需要 --force）

查询注意事项

1. 查询前先搜索

获取接口详情前，必须先用 search_paths 确认接口存在：

# 错误做法：直接查询可能不存在的接口
python3 scripts/apifox.py get_path --path "/rpc/xxx/yyy" --method POST

# 正确做法：先搜索确认存在
python3 scripts/apifox.py search_paths --keyword "xxx"
# 然后根据搜索结果获取详情
python3 scripts/apifox.py get_path --path "/rpc/xxx/yyy" --method GET

2. HTTP 方法判断

根据路径特征判断 HTTP 方法：

路径特征	常见方法	示例
/page、/list、/query	GET	分页查询、列表查询
/create、/add	POST	创建资源
/update、/modify	PUT/POST	更新资源
/delete、/remove	DELETE	删除资源
/xxx/{id}	GET	获取单个资源

使用示例

获取接口详情

# 获取接口详情（自动推断模块）
python3 scripts/apifox.py get_path \
    --path "/api/v3/goods/stocks/check/orders" \
    --method POST

# 获取接口并解析 $ref 引用
python3 scripts/apifox.py get_path \
    --path "/api/v3/goods/stocks/check/orders" \
    --method POST \
    --include_refs true

获取 Schema 定义

# 获取 Schema 定义
python3 scripts/apifox.py get_schema --name CreateGoodsStockCheckOrderReq

搜索接口

# 搜索盘点相关接口
python3 scripts/apifox.py search_paths --keyword "盘点"

# 搜索特定模块的接口
python3 scripts/apifox.py search_paths --keyword "库存" --module api.stocks

# 按方法过滤
python3 scripts/apifox.py search_paths --keyword "order" --method POST --limit 10

模块查询

# 列出所有模块
python3 scripts/apifox.py list_modules

# 获取特定模块的所有接口
python3 scripts/apifox.py get_module --module api.stocks

文档管理

# 初始化环境（首次使用前必须执行）
python3 scripts/apifox.py init

# 查看缓存状态
python3 scripts/apifox.py status

# 刷新文档（从 Apifox 获取最新数据）
python3 scripts/apifox.py refresh_oas

# 清除缓存
python3 scripts/apifox.py clear_cache --force

输出格式

所有命令返回 JSON 格式：

{
  "success": true,
  "data": "返回的数据"
}

错误时返回：

{
  "success": false,
  "error": "错误信息"
}

缓存结构

cache/
├── meta.json              # 元数据 + 全局索引
├── modules/               # 按模块拆分的接口数据
│   ├── api.stocks.json    # 库存相关接口
│   ├── rpc.advice.json    # 医嘱相关接口
│   └── ...
└── schemas/               # Schema 定义缓存（按首字母分组）
    ├── a.json             # A 开头的 Schema
    ├── b.json
    ├── ...
    └── _.json             # 非字母开头的 Schema（中文、数字等）

模块命名规则

路径格式	模块名	示例
/api/v3/goods/stocks/xxx	api.stocks	库存模块
/rpc/advice/xxx	rpc.advice	医嘱模块
/api/global-auth/xxx	api.global-auth	认证模块

文件结构

scripts/
├── apifox.py           # Python CLI 实现（命令行入口）
├── apifox_client.py    # 客户端
├── cache_manager.py    # 缓存管理器
├── requirements.txt    # Python 依赖
├── check_env.py        # 环境检查脚本
└── test_apifox.py      # 功能测试脚本

开发工具

环境检查 (check_env.py)

检查环境配置和 API 连接状态：

python3 scripts/check_env.py

检查项目：

• 环境变量是否配置
• Python 依赖是否安装
• 缓存状态
• API 连接测试

使用场景：

• 首次配置后验证环境
• API 连接异常时诊断
• 修改环境变量后确认生效

功能测试 (test_apifox.py)

冒烟测试套件，验证核心功能正常：

python3 scripts/test_apifox.py

测试内容：

• 缓存加载
• 搜索性能（平均应 < 100ms）
• 模块过滤
• 方法过滤
• 接口详情获取
• Schema 获取
• 模块列表

使用场景：

• 修改代码后必须运行，确保功能正常
• 部署前的回归测试
• 性能退化检测

依赖安装 (requirements.txt)

# 安装依赖
pip3 install -r scripts/requirements.txt

开发工作流

修改功能后必须执行冒烟测试：

# 1. 修改代码
vim scripts/cache_manager.py

# 2. 运行测试（必须）
python3 scripts/test_apifox.py

# 3. 测试通过后提交
git add scripts/cache_manager.py
git commit -m "fix: ..."

测试失败时：

• 检查修改是否破坏了现有功能
• 运行 check_env.py 诊断环境问题
• 修复后重新测试直到通过