# Apifox 拉取器 (/docs/plugin-system/builtin-plugins/apifox)



# Apifox 拉取器 [#apifox-拉取器]

本插件用于直接从 Apifox 导入 OpenAPI 文档，无需手动导出本地文件到项目中。

## 主要功能 [#主要功能]

* 支持从 Apifox 项目直接拉取 OpenAPI 文档
* 支持按标签筛选接口范围
* 支持多种 OpenAPI 版本和导出格式
* 支持自定义 Apifox 扩展属性和文件夹标签

> **使用此插件后不再需要设置 `input` 字段。**

## 基本使用 [#基本使用]

```javascript
import { defineConfig } from 'wormajs';
import { apifox } from 'wormajs/plugin';

export default defineConfig({
  generator: [
    {
      // ...
      plugins: [
        // 从 Apifox 项目拉取 OpenAPI 文档
        apifox({
          projectId: 'proj-123',
          apifoxToken: 'token-abc',
        }),
      ],
    },
  ],
});
```

## 配置参数 [#配置参数]

```typescript
interface ApifoxOptions {
  /** Apifox 项目 ID */
  projectId: string;
  /** Apifox 访问令牌 */
  apifoxToken: string;
  /** 语言环境，默认 'zh-CN' */
  locale?: string;
  /** Apifox API 版本，默认 '2024-03-24' */
  apifoxVersion?: string;
  /** 按标签筛选接口 */
  selectedTags?: string[];
  /** 排除指定标签的接口 */
  excludedByTags?: string[];
  /** OpenAPI 版本，默认 '3.0' */
  oasVersion?: '2.0' | '3.0' | '3.1';
  /** 导出格式，默认 'JSON' */
  exportFormat?: 'JSON' | 'YAML';
  /** 是否包含 Apifox 扩展属性，默认 false */
  includeApifoxExtensionProperties?: boolean;
  /** 是否将文件夹路径作为标签，默认 false */
  addFoldersToTags?: boolean;
}

function apifox(options: ApifoxOptions): ApiPlugin;
```

### 参数说明 [#参数说明]

| 参数名                                | 类型                        | 默认值            | 描述               |
| ---------------------------------- | ------------------------- | -------------- | ---------------- |
| `projectId`                        | `string`                  | —              | Apifox 项目 ID     |
| `apifoxToken`                      | `string`                  | —              | Apifox 访问令牌      |
| `locale`                           | `string`                  | `'zh-CN'`      | 语言环境             |
| `apifoxVersion`                    | `string`                  | `'2024-03-24'` | Apifox API 版本    |
| `selectedTags`                     | `string[]`                | —              | 按标签筛选接口          |
| `excludedByTags`                   | `string[]`                | —              | 排除指定标签的接口        |
| `oasVersion`                       | `'2.0' \| '3.0' \| '3.1'` | `'3.0'`        | OpenAPI 版本       |
| `exportFormat`                     | `'JSON' \| 'YAML'`        | `'JSON'`       | 导出格式             |
| `includeApifoxExtensionProperties` | `boolean`                 | `false`        | 是否包含 Apifox 扩展属性 |
| `addFoldersToTags`                 | `boolean`                 | `false`        | 是否将文件夹路径作为标签     |

## 高级用法 [#高级用法]

### 按标签筛选接口 [#按标签筛选接口]

```javascript
apifox({
  projectId: 'proj-123',
  apifoxToken: 'token-abc',
  selectedTags: ['order', 'user'],
});
```

### 排除指定标签的接口 [#排除指定标签的接口]

```javascript
apifox({
  projectId: 'proj-123',
  apifoxToken: 'token-abc',
  excludedByTags: ['test', 'deprecated'],
});
```

### 自定义 OpenAPI 版本和导出格式 [#自定义-openapi-版本和导出格式]

```javascript
apifox({
  projectId: 'proj-123',
  apifoxToken: 'token-abc',
  oasVersion: '3.1',
  exportFormat: 'YAML',
});
```

### 包含 Apifox 扩展属性 [#包含-apifox-扩展属性]

```javascript
apifox({
  projectId: 'proj-123',
  apifoxToken: 'token-abc',
  includeApifoxExtensionProperties: true,
});
```