abc-apifox

ABC Apifox Skill

This skill provides the ABC Healthcare Cloud API documentation query function.

Environment Configuration

Required Environment Variables

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

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

Get Token: Log in to Apifox > Account Settings > API Access Token

Dependency Installation

pip3 install requests

First Use: Initialize Cache

Before first use, you need to initialize the cache (only needs to be done once). Run the following command:

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

The initialization process automatically:

Checks and installs Python dependencies (requests)
Runs environment checks (verifies APIFOX_ACCESS_TOKEN configuration)
Downloads the latest API documentation from Apifox and builds the cache

After the cache is initialized, subsequent queries read directly from local storage without needing to reinitialize. To update the cache, you can use the refresh_oas command.

How It Works

Cache Architecture: A cache structure split by module

Smart Splitting: Interfaces are split by module, Schemas are grouped by first letter
On-Demand Loading: Only relevant module files are loaded during queries
Cache Persistence: The cache is permanently valid; you need to manually refresh to get the latest documentation
Automatic Protection: The cache status is automatically checked internally during queries

Usage

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

All commands return output in JSON format by default.

Command List

Interface Query

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

Documentation Management

Command	Description
`init`	Initialize environment (install dependencies, check configuration, download cache)
`refresh_oas`	Refresh OpenAPI documentation
`status`	View cache status
`clear_cache`	Clear local cache (requires `--force`）

Query Notes

1. Search before querying

Before getting interface details, you must first use search_paths to confirm the interface exists：

# 错误做法：直接查询可能不存在的接口
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 method determination

Determine the HTTP method based on path characteristics:

Path Characteristics	Common Methods	Example
`/page`、`/list`、`/query`	GET	Paged query, list query
`/create`、`/add`	POST	Create resource
`/update`、`/modify`	PUT/POST	Update resource
`/delete`、`/remove`	DELETE	Delete resource
`/xxx/{id}`	GET	Get a single resource

Usage Examples

Get interface details

# 获取接口详情（自动推断模块）
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

Get Schema definition

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

Search interfaces

# 搜索盘点相关接口
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

Module query

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

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

Documentation management

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

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

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

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

Output Format

All commands return JSON format:

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

On error, returns:

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

Cache Structure

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

Module Naming Rules

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

File Structure

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

Development Tools

Environment Check (`check_env.py`)

Check environment configuration and API connection status:

python3 scripts/check_env.py

Check Item：

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

Use Cases：

Verify environment after initial configuration
Diagnose when API connection is abnormal
Confirm changes take effect after modifying environment variables

Functional Test (`test_apifox.py`)

Smoke test suite to verify that core functions work properly:

python3 scripts/test_apifox.py

Test Content：

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