abc-apifox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ABC Apifox Skill

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

This skill provides ABC Medical Cloud API document query functionality.

环境配置

Environment Configuration

必需的环境变量

Required Environment Variables

使用前需要配置 Apifox Access Token：

bash

undefined

Before use, you need to configure the Apifox Access Token:

bash

undefined

设置 Apifox Access Token（必需）

export APIFOX_ACCESS_TOKEN="你的 Apifox Access Token"

设置项目 ID（可选，默认为 4105462）

export APIFOX_PROJECT_ID="4105462"

undefined

export APIFOX_PROJECT_ID="4105462"

undefined

获取 Apifox Access Token

Obtain Apifox Access Token

登录 Apifox
进入账号设置 > API 访问令牌
创建新的访问令牌
复制 Token 并配置到环境变量

Log in to Apifox
Go to Account Settings > API Access Token
Create a new access token
Copy the Token and configure it in the environment variable

依赖安装

Dependency Installation

bash

undefined

bash

undefined

安装 Python 依赖

pip3 install requests

undefined

pip3 install requests

undefined

工作原理

Working Principle

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

首次使用：从 Apifox API 获取 OpenAPI 文档
智能拆分：
- 接口按模块拆分（api.stocks、rpc.advice 等）
- Schema 按首字母分组（A-Z + 非字母）
按需加载：查询时只加载相关模块文件
缓存持久：缓存永久有效，需要手动刷新获取最新文档

Cache Architecture: Module-split Cache Structure

First Use: Retrieve OpenAPI documents from Apifox API
Intelligent Splitting:
- Interfaces are split by module (api.stocks, rpc.advice, etc.)
- Schemas are grouped by initial letter (A-Z + non-letters)
On-demand Loading: Only load relevant module files during queries
Persistent Cache: The cache is permanently valid, and manual refresh is required to get the latest documents

使用方式

Usage

bash

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

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

bash

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

All commands return JSON format output by default.

命令列表

Command List

接口查询

Interface Query

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

Command	Description
`get_path`	Get interface details (automatically infers module)
`get_schema`	Get Schema definitions
`search_paths`	Search interfaces (keyword matching)
`list_modules`	List all modules
`get_module`	Get all interfaces of a module

文档管理

Document Management

命令	说明
`refresh_oas`	刷新 OpenAPI 文档
`status`	查看缓存状态
`clear_cache`	清除本地缓存（需要 `--force` ）

Command	Description
`refresh_oas`	Refresh OpenAPI documents
`status`	View cache status
`clear_cache`	Clear local cache (requires `--force` )

使用示例

Usage Examples

获取接口详情

Get Interface Details

bash

undefined

bash

undefined

获取接口详情（自动推断模块）

./scripts/apifox get_path
--path "/api/v3/goods/stocks/check/orders"
--method POST

获取接口并解析 $ref 引用

./scripts/apifox get_path
--path "/api/v3/goods/stocks/check/orders"
--method POST
--include_refs true

undefined

./scripts/apifox get_path
--path "/api/v3/goods/stocks/check/orders"
--method POST
--include_refs true

undefined

获取 Schema 定义

Get Schema Definitions

bash

undefined

bash

undefined

获取 Schema 定义

./scripts/apifox get_schema --name CreateGoodsStockCheckOrderReq

undefined

./scripts/apifox get_schema --name CreateGoodsStockCheckOrderReq

undefined

搜索接口

Search Interfaces

bash

undefined

bash

undefined

搜索盘点相关接口

./scripts/apifox search_paths --keyword "盘点"

搜索特定模块的接口

./scripts/apifox search_paths --keyword "库存" --module api.stocks

按方法过滤

./scripts/apifox search_paths --keyword "order" --method POST --limit 10

undefined

./scripts/apifox search_paths --keyword "order" --method POST --limit 10

undefined

模块查询

Module Query

bash

undefined

bash

undefined

列出所有模块

./scripts/apifox list_modules

获取特定模块的所有接口

./scripts/apifox get_module --module api.stocks

undefined

./scripts/apifox get_module --module api.stocks

undefined

文档管理

Document Management

bash

undefined

bash

undefined

查看缓存状态

./scripts/apifox status

刷新文档（从 Apifox 获取最新数据）

./scripts/apifox refresh_oas

清除缓存

./scripts/apifox clear_cache --force

undefined

./scripts/apifox clear_cache --force

undefined

输出格式

Output Format

所有命令返回 JSON 格式：

json

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

错误时返回：

json

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

All commands return JSON format:

json

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

Returns on error:

json

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

Claude 使用方式

Usage with Claude

当用户需要查询 API 文档时：

理解需求：确定要查询的接口或 Schema
构建命令：根据需求选择合适的命令
执行脚本：使用 Bash 工具运行
分析结果：解析返回的接口/Schema 定义

示例工作流：

用户: "查看盘点单接口的定义"

Claude:
1. ./scripts/apifox search_paths --keyword "盘点"
2. 从结果中找到相关接口路径
3. ./scripts/apifox get_path --path "/api/v3/goods/stocks/check/orders" --method POST
4. 分析返回的请求体 CreateGoodsStockCheckOrderReq
5. 如需查看 Schema: ./scripts/apifox get_schema --name CreateGoodsStockCheckOrderReq

When users need to query API documents:

Understand Requirements: Determine the interface or Schema to query
Build Command: Select the appropriate command based on requirements
Execute Script: Run using Bash tools
Analyze Results: Parse the returned interface/Schema definitions

Example Workflow:

User: "View the definition of the inventory check interface"

Claude:
1. ./scripts/apifox search_paths --keyword "盘点"
2. Find the relevant interface path from the results
3. ./scripts/apifox get_path --path "/api/v3/goods/stocks/check/orders" --method POST
4. Analyze the returned request body CreateGoodsStockCheckOrderReq
5. If Schema viewing is needed: ./scripts/apifox get_schema --name CreateGoodsStockCheckOrderReq

缓存结构

Cache Structure

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

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

模块命名规则

Module Naming Rules

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

Path Format	Module Name	Example
`/api/v3/goods/stocks/xxx`	`api.stocks`	Inventory Module
`/rpc/advice/xxx`	`rpc.advice`	Medical Advice Module
`/api/global-auth/xxx`	`api.global-auth`	Authentication Module

文件结构

File Structure

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

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

首次使用

First Use

bash

undefined

bash

undefined

配置环境变量后首次运行

./scripts/apifox status

自动从 Apifox 获取文档并建立缓存

正在从 Apifox 获取项目 4105462 的 OpenAPI 文档...

正在清空旧缓存...

正在按模块拆分接口...

正在保存 Schema（分组格式）...

导入完成!

undefined

undefined

开发工具

Development Tools

环境检查 (

check_env.py

)

Environment Check (

check_env.py

)

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

bash

python3 scripts/check_env.py

检查项目：

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

使用场景：

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

Check environment configuration and API connection status:

bash

python3 scripts/check_env.py

Check Items:

Whether environment variables are configured
Whether Python dependencies are installed
Cache status
API connection test

Usage Scenarios:

Verify environment after initial configuration
Diagnose when API connection is abnormal
Confirm effectiveness after modifying environment variables

功能测试 (

test_apifox.py

)

Function Test (

test_apifox.py

)

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

bash

python3 scripts/test_apifox.py

测试内容：

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

使用场景：

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

Smoke test suite to verify normal core functions:

bash

python3 scripts/test_apifox.py

Test Content:

Cache loading
Search performance (average should be < 100ms)
Module filtering
Method filtering
Interface details retrieval
Schema retrieval
Module list

Usage Scenarios:

Must run after modifying code to ensure normal functionality
Regression testing before deployment
Performance degradation detection

依赖安装 (

requirements.txt

)

Dependency Installation (

requirements.txt

)

bash

undefined

bash

undefined

安装依赖

pip3 install -r scripts/requirements.txt

undefined

pip3 install -r scripts/requirements.txt

undefined

开发工作流

Development Workflow

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

bash

undefined

Smoke tests must be executed after modifying functions:

bash

undefined

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` 诊断环境问题
- 修复后重新测试直到通过

git add scripts/cache_manager.py git commit -m "fix: ..."


**When Tests Fail**:
- Check if modifications have broken existing functionality
- Run `check_env.py` to diagnose environment issues
- Fix and retest until passed