# api_skill

**Repository Path**: idnex/api_skill

## Basic Information

- **Project Name**: api_skill
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenAPI Parser & Generator

解析 OpenAPI/Swagger 文档并生成 TypeScript 类型定义和 API 接口文件。

## 功能特性

- 支持 OpenAPI 3.0.x / 3.1.x 和 Swagger 2.0
- 支持 JSON 和 YAML 格式
- 自动生成 TypeScript 类型定义
- 自动生成 API 接口函数
- 支持从 URL 或本地文件解析
- 可配置的代码生成选项

## 安装依赖

```bash
pip install -r requirements.txt
```

## 使用方法

### 1. 解析 OpenAPI 文档并生成所有文件

```bash
python cli.py parse <文档路径> [--output OUTPUT] [--config CONFIG]
```

**示例：**
```bash
# 解析本地 JSON 文件
python cli.py parse ./api-docs.json

# 解析 YAML 文件并指定输出目录
python cli.py parse ./swagger.yaml -o src/api

# 从 URL 解析
python cli.py parse https://api.example.com/swagger.json
```

### 2. 仅生成 TypeScript 类型

```bash
python cli.py generate-types <文档路径> [--output OUTPUT]
```

### 3. 仅生成 API 接口

```bash
python cli.py generate-api <文档路径> [--output OUTPUT] [--axios|--fetch]
```

### 4. 查看配置信息

```bash
python cli.py info
```

## 配置选项

配置文件 `config.yaml` 支持以下选项：

```yaml
openapi:
  input_path: "./api-docs.json"    # 默认输入路径
  output_path: "src/api"            # 默认输出路径
  request_lib: "axios"              # 请求库：axios 或 fetch
  type_style: "interface"           # 类型风格：interface 或 type
  generate_comments: true           # 是否生成注释
  prettier_format: true             # 是否使用 Prettier 格式化
  split_by_tag: true                # 是否按标签分组
  use_namespace: true               # 是否使用命名空间

naming:
  interface_prefix: "I"             # 接口前缀
  type_prefix: ""                   # 类型前缀
  use_camel_case: true              # 是否使用驼峰命名

output:
  types_dir: "types"                # 类型文件目录
  services_dir: "services"          # API 文件目录
  create_index: true                # 是否创建索引文件
  group_by_tag: true                # 是否按标签分组
```

## 输出结构

```
src/api/
├── types/              # TypeScript 类型定义
│   ├── User.ts
│   ├── CreateUserRequest.ts
│   └── ...
├── services/           # API 接口函数
│   ├── user.ts
│   ├── order.ts
│   └── ...
└── index.ts            # 统一导出
```

## 生成的代码示例

### TypeScript 类型定义

```typescript
export interface IUser {
  /** User ID */
  id: number;
  /** Username */
  username: string;
  /** Email address */
  email: string;
  /** User role */
  role?: 'admin' | 'user' | 'guest';
  /** Creation time */
  createdAt?: string;
}
```

### API 接口函数

```typescript
import request from '@/utils/request';
import type { IGetUsersParams, IGetUsersResponse } from './types';

/**
 * Get user list
 * Retrieve a list of users with pagination
 */
export function getUsers(params: IGetUsersParams): Promise<IGetUsersResponse> {
  return request.get('/api/users', { params });
}
```

## 支持的 OpenAPI 特性

- ✅ 基本数据类型（string, number, integer, boolean, array, object）
- ✅ 枚举类型
- ✅ 引用（$ref）
- ✅ 必填/可选字段
- ✅ 数组类型
- ✅ 嵌套对象
- ✅ 路径参数
- ✅ 查询参数
- ✅ 请求体
- ✅ 响应类型
- ✅ 标签分组
- ✅ 操作描述和摘要

## 测试

使用提供的测试文件：

```bash
python cli.py parse test-api.json -o test-output
```

## 注意事项

1. 生成的类型文件会覆盖已存在的同名文件
2. 建议将自定义代码写在单独的文件中
3. 确保项目中已安装配置的请求库（axios 或 fetch）
4. 生成的代码需要 `@/utils/request` 模块支持

## 与其他 Skills 协作

此工具是 framework-code-search 的子 skill，通常与其他 skills 配合使用：

1. **openapi** → 解析接口文档，生成类型和 API
2. **code-search** → 搜索相关代码模块
3. **页面生成** → 使用生成的类型和搜索到的模块生成页面

## 示例完整流程

```bash
# 1. 解析 OpenAPI 文档
python cli.py parse ./swagger.json

# 2. 搜索相关表格组件
python ../code-search/cli.py search "表格" -c vueHook

# 3. AI 根据生成的 API 和搜索到的组件生成页面
```

## 版本历史

- **v1.0.0** - 初始版本，支持基本的 OpenAPI 解析和代码生成