# easy-yapi

**Repository Path**: waxbegonia/easy-yapi

## Basic Information

- **Project Name**: easy-yapi
- **Description**: IntelliJ plugin that generates API docs from Java/Kotlin projects and syncs them directly to YApi, with built-in request testing and multi-channel export.
- **Primary Language**: Kotlin
- **License**: AGPL-3.0
- **Default Branch**: hd
- **Homepage**: https://easyyapi.github.io
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 13
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Easy YAPI

一个 IntelliJ IDEA 插件，用于将 Java/Kotlin Spring MVC Controller、Feign 客户端和 gRPC 服务中的 API 注解导出到 YAPI 文档管理平台。

## 功能特性

### 框架支持

- **Spring MVC 注解解析**：支持 `@RestController`、`@Controller`、`@RequestMapping`、`@GetMapping`、`@PostMapping`、`@PutMapping`、`@DeleteMapping`、`@PatchMapping` 等注解
- **Feign 客户端支持**：支持解析 Feign 客户端接口中的 `@FeignClient`、`@RequestLine`、`@Param` 等注解
- **gRPC 服务支持**：支持解析 gRPC 服务定义，自动生成 API 文档

### 参数与响应

- **参数解析**：支持 `@RequestBody`、`@RequestParam`、`@PathVariable`、`@RequestHeader`、`@ModelAttribute`、`@CookieValue` 等注解的参数提取
- **响应体解析**：自动解析方法返回类型，包括泛型包装类型（如 `Result<T>`、`ResponseEntity<T>`）

### 文档与数据

- **Javadoc / Swagger 支持**：支持从 Javadoc、`@ApiOperation`、`@Operation`、`@ApiModelProperty`、`@Schema` 等提取 API 描述信息
- **Mock 数据生成**：根据参数名称和类型自动生成 Mock.js 兼容的模拟数据表达式
- **JSON Schema / JSON5 支持**：支持以 JSON Schema 或 JSON5 格式生成请求/响应体

### 导出功能

- **API 去重**：自动检测已存在的 API（按路径+方法匹配），支持更新或跳过
- **多项目/模块支持**：支持 Maven/Gradle 多模块项目的令牌查找
- **文件夹批量导出**：支持右键点击文件夹/包，递归扫描并批量导出所有 Controller
- **多渠道导出**：支持从不同菜单入口快速导出
- **自动扫描**：支持在分支变更或文件变更时自动扫描

## 安装

### 从 JetBrains Marketplace 安装

在 IntelliJ IDEA 中，打开 `Settings/Preferences` → `Plugins` → `Marketplace`，搜索 **Easy YAPI ** 并安装。

### 手动安装

1. 下载最新版本的插件 JAR 文件
2. 打开 `Settings/Preferences` → `Plugins` → `⚙` → `Install Plugin from Disk...`
3. 选择下载的 JAR 文件并重启 IDE

## 配置

安装后，在 `Settings/Preferences` 中找到 **Easy YAPI ** 配置页面：

| 配置项 | 说明 |
|--------|------|
| **YAPI Server** | YAPI 服务器基础 URL |
| **Tokens** | 各模块的私有令牌（格式：`模块名=令牌`，每行一个） |
| **Export Mode** | 导出模式：总是更新 / 从不更新 / 询问 / 内容变更时更新 |
| **Request Body JSON5** | 请求体是否使用 JSON5 格式 |
| **Response Body JSON5** | 响应体是否使用 JSON5 格式 |
| **Timeout (seconds)** | HTTP 请求超时时间（秒） |
| **Allow unsafe SSL** | 是否允许不安全的 SSL 连接 |
| **Auto scan on branch change** | 分支变更时是否自动扫描 |
| **Auto scan on file change** | 文件变更时是否自动扫描 |

## 使用方法

### 右键菜单导出

在 IntelliJ IDEA 中，右键点击 Spring MVC Controller 类或方法，选择 **Export to YAPI** 即可导出 API 文档。

### Generate 菜单导出

通过 `Generate` 菜单 → `EasyApi` → `Export to YAPI` 导出。

### 快速导出子菜单

右键点击 Controller 类，可在快速操作菜单中选择导出。

## 项目结构

```
src/main/kotlin/cn/xszhome/eayapi/
├── /
│   ├── model/                    # 导出模型定义
│   │   ├── ApiModels.kt          # API 端点、参数、头、HTTP 方法等模型
│   │   ├── ExportContext.kt      # 导出上下文
│   │   ├── ExportMetadata.kt     # 导出元数据接口
│   │   ├── ExportResult.kt       # 导出结果（成功/失败/取消）
│   │   └── PathSelector.kt       # 多路径选择策略
│   └── yapi/
│       ├── DefaultYapiApiClient.kt # YAPI API 客户端实现
│       ├── YapiApiClient.kt       # YAPI API 客户端接口
│       ├── YapiApiClientProvider.kt # YAPI 客户端提供者
│       ├── Yapi.kt        # 核心导出器
│       ├── YapiFormatter.kt       # YAPI 文档格式化器
│       ├── YapiSettingsHelper.kt  # YAPI 设置辅助类
│       ├── YapiUrls.kt            # YAPI URL 工具
│       ├── UpdateDecision.kt      # 更新决策机制
│       ├── JsonSchemaBuilder.kt   # JSON Schema 构建器
│       ├── MockDataGenerator.kt   # Mock 数据生成器
│       └── MockRuleLoader.kt      # Mock 规则加载器
├── http/                          # HTTP 客户端
├── ide/
│   ├── action/                    # IDE 动作
│   └── listener/                  # IDE 事件监听器
│   └── support/                   # IDE 支持工具
├── psi/
│   ├── model/                     # PSI 模型
│   └── type/                      # PSI 类型处理
├── settings/                      # 设置相关
└── util/                          # 工具类
```

## 构建与运行

### 前置条件

- Java 17+
- Gradle
- IntelliJ IDEA 2024.x

### 构建

```bash
./gradlew build
```

### 运行

```bash
./gradlew runIde
```

## 导出模式说明

| 模式 | 说明 |
|------|------|
| **ALWAYS_UPDATE** | 总是更新已存在的 API |
| **NEVER_UPDATE** | 已存在时跳过，仅创建新 API |
| **ALWAYS_ASK** | 始终询问用户（在独立模式下等同于 ALWAYS_UPDATE） |
| **UPDATE_IF_CHANGED** | 仅当内容有变更时更新 |

## 许可证

本项目基于 MIT 许可证开源。

## 贡献

欢迎提交 Issue 和 Pull Request。