Update docs.

jetplugins · Sep 14, 2021 · 7c4a663 · 7c4a663
1 parent 53abe9f
commit 7c4a663
Show file tree

Hide file tree

Showing 2 changed files with 106 additions and 28 deletions.
diff --git a/doc/GUIDE.md b/doc/GUIDE.md
@@ -1,27 +1,103 @@
-# Yapi X 使用指南
-## 开始
-## 文档
+# 使用指南
+重要的事情说三遍！无依赖、无成本、开箱即用，只需要花几分钟了解下。
+
+## 快速开始
+1. 安装插件: [Yapi x](https://plugins.jetbrains.com/plugin/17425-yapi-x)
+2. 添加配置文件: .yapix, 内容: `yapiProjectId=你的项目id`
+3. 选中上传的方法: 执行"Upload To YApi"
+
+- 支持整个类、多个类、当个方法API文档上传
+- 插件配置路径: File -> Settings -> Tools -> Yapi X
+
+提示: 默认情况下右键菜单是"Upload To YApi", 可通过插件菜单配置为Rap2, Eolinker等
+
+## 文档生成规则
+标准的Javadoc文档就能生成很好的API文档，对于生成文档的准确性有两个建议。
+1. 文档注释: 类、方法、字段文档注释应完善
+2. 使用实体类: 接收参数、响应参数，避免使用map等类型
+
+TODO
+
 ## 平台
-## 配置
+目前支持多个平台YApi, Rap2, Eolinker，包括公有部署和私有部署，支持账户密码登录。
+
+#### YApi
+对于YApi支持3种登录方式：默认, LDAP, 项目token, 推荐用账户密码方式，对于统一登录无法支持，请使用projectToken方式上传。
+- YApi服务地址: 示范: http://yapi.smart-xwork.cn
+- 获取项目id: http://yapi.smart-xwork.cn/project/35523/interface/api
+- 获取项目token: 打开项目 -> 设置 -> token配置
+
+#### Rap2
+- 获取项目id: http://rap2.taobao.org/repository/editor?id=290411 , 290411
+
+#### Eolinker
+目前支持eolinker5.0版本，仅测试了官方提供的sass版本: https://riag.w.eolinker.com
+
+
+## 配置文件
 大多数情况下您只需要配置关联的项目标识（xxxProjectId）即可，更多配置项可满足你的99%的场景。
-```properties
-# 项目id
-yapiProjectId=
-rap2ProjectId=
-eolinkerProjectId=
-
-# 包装类全称: 场景是有配置spring全局过滤器包装统一返回值的情况
-returnWrapType=
-# 解包装类型全称: 场景是有些返回类型不希望被统一spring过滤器包装
-returnUnwrapTypes=
-# 参数忽略类型全称: 场景是自定义注入了一些参数类型不是由客户端上传
-parameterIgnoreTypes=
-# 自定义bean配置: 参见本项目resources/.yapix
-beans[xxx]=<JSON of bean: BeanCustom>
-# 自定义配置mock规则: 参见内置resource/.yapix
-mockRules=<JSON Array: List<MockRule>
-# 时间默认格式: @DateTimeFormat, @JsonFormat优先, 如果是数字类型值: integer
-dateTimeFormatMvc=yyyy-MM-dd HH:mm:ss
-dateTimeFormatJson=yyyy-MM-dd HH:mm:ss
-```
-备注: 对于list类型值支持英文逗号分隔、允许空格.
+
+- 文件目录：项目模块根目录
+- 文件名称: .yapix
+- 文件格式: properties
+#### 配置项
+| 名称 | 类型 | 描述 | 备注 |
+| :---  | :--- | :--- | :--- |
+| yapiProjectId | integer | YApi项目id |
+| rap2ProjectId | integer | Rap2项目id |
+| eolinkerProjectId | string | Eolinker项目id |
+| yapiUrl | string | YApi服务地址 | 场景：插件无法支持YApi统一登录方式，此时可使用项目token方式 |
+| yapiProjectToken | string | YApi项目访问token |
+|  | | |
+| returnWrapType | string | 方法返回值，统一包装类限定名 | 场景: spring统一配置了返回包装类 |
+| returnUnwrapTypes | string | 方法返回值，指定不需要包装的类 | 场景: 某些类不需要spring统一包装, 多个用英文逗号分割 |
+| parameterIgnoreTypes | list&lt;string> | 方法参数忽略的类全称 | 场景: 某些方法参数不是由浏览器客户端上传到 |
+|  | | |
+| dateTimeFormatMvc | string | 默认返回时间格式(表单) | 默认格式: yyyy-MM-dd HH:mm:ss, 时间轴配置: integer |
+| dateTimeFormatJson | string | 默认返回时间格式(json) | 默认格式: yyyy-MM-dd HH:mm:ss, 时间轴配置: integer |
+|  | | |
+| beans[X] | BeanCustom | 自定义bean配置 |
+| mockRules | List&lt;MockRule> | 自定义mock规则 |
+
+#### beans
+- 概述: 自定义bean配置, Map类型: Key是类限定名, Value是配置项
+- 场景: 引入的第三方包希望重写字段名称、备注等.
+- 文档:
+    ```json
+    {
+    	"includes": [],		// 只包含的字段名
+    	"excludes": [],		// 排除的字段名
+    	"fileds": {
+    		"pageNumber": { 	// 指定字段配置
+    			"name": "",			// 参数名
+    			"description": "",	// 参数描述
+    			"type": "",			// 参数类型: boolean, integer, string, float, object
+    			"required": true, 	// 是否必须
+    			"mock": "", 		// mock: 参见mock.js
+    			"defaultValue":"" 	// 默认值
+    		}
+    	}
+    }
+    ```
+- 示例:
+    ```properties
+    beans[org.springframework.data.domain.Pageable]= { \
+            "includes": ["pageNumber", "pageSize", "sort"], \
+            "fields": { \
+                "pageNumber": { "name": "page", "description": "页码" }, \
+                "pageSize": { "name": "size", "description": "每页大小" }, \
+                "sort": { "name": "sort", "type": "string", "description": "排序" } \
+            } \
+    }
+    ```
+### mockRules
+- 概述: 根据业务特点可以自定义mock规则
+- 文档:
+    ```json
+    [{
+    	"name": "图标",               // 备注
+    	"type": "string",            // 匹配类型
+    	"match": "avatar|icon",      // 匹配字段名: 正则表达式，忽略大小写
+    	"mock": "@image('100x100')"  // mock值
+    }]
+    ```
diff --git a/src/main/resources/META-INF/plugin.xml b/src/main/resources/META-INF/plugin.xml
@@ -1,7 +1,7 @@
 <idea-plugin>
     <id>yapix</id>
     <name>Yapi X</name>
-    <version>0.0.5.2021091302</version>
+    <version>0.6</version>
     <vendor url="https://github.com/jetplugins">Jetplugins</vendor>
 
     <description><![CDATA[
@@ -61,12 +61,14 @@
     </actions>
 
     <change-notes><![CDATA[
-      <p>0.0.6</p>
+      <p>0.6</p>
       <ul>
+        <li>Supports @ignore tag.</li>
+        <li>Supports parse map type.</li>
         <li>Add YApi supports LDAP login.</li>
         <li>Add YApi supports token auth.</li>
-        <li>Add parse map type.</li>
         <li>Add basic swagger annotations.</li>
+        <li>Optimize rap2 remove request body wrap root.</li>
         <li>Fix copy as curl escape.</li>
       </ul>
       <p>0.0.5</p>