# Idea_rest2dd

**Repository Path**: le_xiaobei/idea_rest2dd

## Basic Information

- **Project Name**: Idea_rest2dd
- **Description**: idea插件，用于接口文档数据同步到钉钉文档
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Idea_rest2dd

## 介绍

IntelliJ IDEA 插件，用于将 REST 接口文档数据同步到钉钉知识库文档。

支持的 IDEA 版本：2025.1 - 2025.3 (build 251.* - 253.*)

支持 Spring 系列框架（Spring MVC / Spring Boot）

### 环境要求

- **JDK 17**：编译和运行需要 JDK 17
- **Gradle 8.0+**：构建工具版本要求
- **IntelliJ IDEA 2025.1+**：插件兼容的 IDE 版本

### 核心功能

1. **获取 REST 接口信息**
   - 解析 @RestController 类下的全部接口信息
   - 支持通过 Swagger 注解获取接口详细信息
   - 参考：https://gitee.com/liuzhihang/doc-view
   - 支持 validation、swagger 等注解
   - Markdown 接口查看、预览、复制、导出
   - 支持自定义生成接口的 Markdown 模板
   - 支持界面编辑文档、注释，并同步保存到代码注释或 Swagger 注解中
   - 支持在编辑实体界面，将实体复制为 Json 字符串
   - 支持自定义配置

2. **将接口信息同步到钉钉文档中**
   - 支持在线创建知识库
   - 接口文档：https://open.dingtalk.com/document/development/new-knowledge-base
   - 支持在线查看知识库列表
   - 接口文档：https://open.dingtalk.com/document/development/get-knowledge-base-list
   - 支持在线查看文档列表
   - 接口文档：https://open.dingtalk.com/document/development/get-node-list
   - 支持在线创建知识库文档
   - 接口文档：https://open.dingtalk.com/document/development/create-team-space-document
   - 支持在线更新知识库文档
   - 接口文档：https://open.dingtalk.com/document/development/api-doc-updatecontent

## 软件架构

### 项目结构

```
idea-rest2dd/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/
│       │       └── rest2dd/
│       │           ├── action/          # 插件 Action
│       │           ├── dingtalk/        # 钉钉 API 客户端
│       │           ├── generator/       # Markdown 生成器
│       │           ├── listener/        # 项目监听器
│       │           ├── model/           # 数据模型
│       │           ├── parser/          # REST 控制器解析器
│       │           ├── service/         # 项目服务
│       │           └── ui/              # UI 界面
│       └── resources/
│           └── META-INF/
│               └── plugin.xml           # 插件配置
├── build.gradle                         # Gradle 构建配置
├── gradle.properties                    # Gradle 属性
└── settings.gradle                      # Gradle 设置
```

### 技术栈

- Kotlin
- IntelliJ Platform SDK
- OkHttp3 (HTTP 客户端)
- Gson (JSON 处理)

## 安装教程

1. 克隆项目到本地
2. 执行 `./gradlew buildPlugin` 构建插件
3. 在 IDEA 中打开 `Settings -> Plugins -> Install Plugin from Disk`
4. 选择生成的 `build/distributions/*.zip` 文件
5. 重启 IDEA

## 使用说明

### 📍 插件入口

**REST to DingTalk** 插件提供以下两种访问方式：

1. **项目视图右键菜单**
   - 在 Project 视图中，右键点击项目或任意文件
   - 在弹出的菜单底部找到 "REST to DingTalk" 选项
   - 点击即可打开插件工具窗口

2. **编辑器右键菜单**
   - 在代码编辑器中任意位置右键
   - 在弹出的菜单底部找到 "REST to DingTalk" 选项
   - 点击即可打开插件工具窗口

---

### ✅ 安装确认步骤

#### 1. 检查插件是否已安装
   - 打开 `File` → `Settings` → `Plugins`
   - 在已安装列表中查找 "REST to DingTalk"
   - 确认插件版本号显示正常

#### 2. 验证插件功能
   - 打开任意 Java Spring 项目
   - 确保项目中包含带有 `@RestController` 注解的类
   - 通过右键菜单打开插件工具窗口
   - 应能看到左侧的接口列表和右侧的文档预览

#### 3. 配置钉钉信息（可选，用于同步功能）
   - 在工具窗口中配置钉钉 AppKey 和 AppSecret
   - 点击"测试连接"验证配置是否正确

---

### 🎯 功能特性

#### 1. 自动解析 REST 接口
- 扫描项目中的所有 `@RestController` 注解类
- 解析 `@RequestMapping`、`@GetMapping`、`@PostMapping` 等注解
- 提取接口的请求方法、路径、参数、返回值等信息

#### 2. 支持 Swagger 注解
- 解析 `@ApiOperation`、`@ApiParam` 等 Swagger 注解
- 获取接口的详细描述和参数说明
- 生成更加丰富的 API 文档

#### 3. Markdown 文档生成
- 自动生成结构化的 Markdown 格式 API 文档
- 支持一键复制到剪贴板
- 可导出为 `.md` 文件进行版本控制

#### 4. 钉钉知识库同步
- 将生成的 API 文档直接同步到钉钉知识库
- 支持选择指定的知识库和文档
- 自动更新已有文档或创建新文档

---

### 📖 详细操作指南

#### 步骤 1：打开插件工具窗口

1. 打开包含 Spring Boot 项目的 IntelliJ IDEA
2. 在 Project 视图中右键点击项目根目录
3. 选择 "REST to DingTalk" 菜单项
4. 插件工具窗口将在界面右侧显示

#### 步骤 2：查看接口列表

- 工具窗口左侧显示项目中所有的 Controller 类
- 点击 Controller 名称展开，查看该类下的所有 API 接口
- 每个接口显示请求方法和路径（如 `GET /api/users`）

#### 步骤 3：生成和预览文档

- 工具窗口右侧实时显示生成的 Markdown 文档
- 点击"生成文档"按钮可重新生成文档
- 文档包含以下内容：
  - 项目名称
  - 接口统计信息
  - 每个接口的详细说明（方法、路径、描述、参数、返回值）

#### 步骤 4：复制文档

- 点击"复制 Markdown"按钮
- 文档内容将被复制到系统剪贴板
- 可粘贴到任意 Markdown 编辑器或文档工具中

#### 步骤 5：同步到钉钉（可选）

**5.1 配置钉钉信息**

在钉钉开放平台创建应用并获取以下信息：
- **AppKey**：应用的唯一标识
- **AppSecret**：应用密钥
- **AgentId**：企业内部应用的 ID

**5.2 选择知识库和文档**

- 从"知识库"下拉框中选择目标知识库
- 从"文档"下拉框中选择已有文档（或留空创建新文档）

**5.3 同步文档**

- 点击"同步到钉钉"按钮
- 等待同步完成
- 状态栏显示同步结果

---

### ❓ 常见问题解答

#### Q1: 为什么打开插件后左侧接口列表为空？

**可能原因：**
- 项目中没有 `@RestController` 注解的类
- 项目未正确导入或未编译

**解决方案：**
- 确保项目是 Spring Boot 项目且包含 REST 控制器
- 执行 `Build` → `Rebuild Project` 重新编译
- 点击工具栏的"刷新"按钮重新扫描

---

#### Q2: 为什么无法同步到钉钉？

**可能原因：**
- 钉钉配置信息未填写或填写错误
- 网络连接问题
- 钉钉知识库权限不足

**解决方案：**
- 检查 AppKey、AppSecret、AgentId 是否正确
- 点击"测试连接"验证配置
- 确认网络可以访问钉钉开放平台 API
- 检查钉钉账号是否有知识库写入权限

---

#### Q3: 生成的文档格式不符合需求？

**自定义方法：**
- 将文档复制到本地 Markdown 文件
- 根据需求手动调整格式
- 使用版本控制工具管理文档

---

#### Q4: 插件支持哪些 IntelliJ IDEA 版本？

**支持版本：**
- IntelliJ IDEA 2025.1 - 2025.3
- Build 号：251.* - 253.*
- 需要 JDK 17 环境

---

#### Q5: 如何卸载插件？

**步骤：**
1. 打开 `File` → `Settings` → `Plugins`
2. 在已安装列表中找到 "REST to DingTalk"
3. 点击右侧的"卸载"按钮
4. 重启 IntelliJ IDEA

---

### 💡 使用技巧

1. **快速生成文档**
   - 项目开发完成后一键生成完整 API 文档
   - 避免手动维护文档，提高效率

2. **团队协作**
   - 将文档同步到钉钉知识库
   - 团队成员可实时查看最新接口定义

3. **版本管理**
   - 将生成的 Markdown 文档提交到 Git 仓库
   - 记录不同版本的接口变化历史

4. **接口测试**
   - 配合 Postman、Apifox 等工具
   - 根据文档快速创建测试用例

---

### 📞 技术支持

如遇到问题或有建议，请通过以下方式联系我们：
- 邮箱：support@rest2dd.com
- GitHub：https://github.com/rest2dd

## 界面预览

- 简洁现代的设计风格
- 清新的蓝色调
- 圆角按钮和输入框
- 适当的阴影效果
- 响应式设计

---

### 🔄 更新日志

**v1.0.0** (2025-01)
- ✨ 初始版本发布
- ✅ 支持 REST 接口解析
- ✅ 支持 Markdown 文档生成
- ✅ 支持钉钉知识库同步

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request