gitbook zh success

Author: astral-data

README.md

@@ -4,7 +4,7 @@
 
 # Languages
 
-- [Complete documen-English](./docs/en/README.md)
+- [Complete documen-English](https://astrals-organization.gitbook.io/php-serialize/php-serialize-en)
 - [完整文档-中文](https://astrals-organization.gitbook.io/php-serialize)
 
 # php-serialize

docs/zh/SUMMARY.md

@@ -14,14 +14,19 @@
 ## 注解类使用
 
 * [属性分组](annotation/group-annotation.md)
-* [输入/输入出名称映射](annotation/alisa-annotation.md)
+* [输入/输出映射](annotation/alisa-annotation.md)
 * [Mapper映射](annotation/mapper-annotation.md)
 * [输入/输出忽略](annotation/ignore-annotation.md)
 * [时间格式映射](annotation/date-annotation.md)
+* [自定义注解](annotation/customer-annotation.md)
 
 ## 参数快速Faker
 
 * [简单属性Faker](faker/value-faker.md)
 * [集合Faker](faker/collection-faker.md)
 * [嵌套Faker](faker/nested-faker.md)
-* [方法Faker](faker/method-faker.md)
+* [方法Faker](faker/method-faker.md)
+
+## 自动创建OpenApi文档
+
+* [基础演示](openapi/base-openapi.md)

docs/zh/annotation/alisa-annotation.md

@@ -1,6 +1,6 @@
-#### 名称映射
+## 名称映射
 
-##### 基础使用
+### 基础使用
 
 ```php
 use Astral\Serialize\Attributes\InputName;
@@ -39,7 +39,7 @@ $userArray = $user->toArray();
 // ]
 ```
 
-##### 多输入/输出名称处理
+### 多输入/输出名称处理
 
 ```php
 use Astral\Serialize\Attributes\InputName;
@@ -104,7 +104,7 @@ $userArray = $user->toArray();
 // ]
 ```
 
-##### 复杂映射场景
+### 复杂映射场景
 
 ```php
 use Astral\Serialize\Serialize;

docs/zh/annotation/customer-annotation.md

@@ -0,0 +1,73 @@
+### 自定义注解类实现
+
+你可以通过自定义注解类，灵活地扩展序列化库的输入输出处理逻辑。
+
+---
+
+#### 入参处理注解类
+
+实现 `InputValueCastInterface` 接口，重写其中的 `match` 和 `resolve` 方法，来自定义输入数据的转换和处理。
+
+- **`match`**：用于判断是否对当前值进行处理，返回 `true` 表示进入 `resolve`。
+- **`resolve`**：对匹配的输入值进行转换，并返回转换后的结果。
+
+示例：给输入值添加自定义前缀的注解类
+
+```php
+use Astral\Serialize\Contracts\Attribute\InputValueCastInterface;
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS)]
+class CustomerInput implements InputValueCastInterface
+{
+    public function __construct(
+        public string $prefix = '',
+    ) {
+    }
+    
+    public function match(mixed $value, DataCollection $collection, InputValueContext $context): bool
+    {
+        // 对所有输入值都生效
+        return true;
+    }
+
+    public function resolve(mixed $value, DataCollection $collection, InputValueContext $context): mixed
+    {
+        // 给输入值添加前缀
+        return $this->prefix . $value;
+    }
+}
+````
+
+### 输出处理注解类
+
+输出处理注解与输入处理注解类似，只是实现的接口不同——需要实现 `OutputValueCastInterface`，用以对序列化输出的值进行自定义转换。
+
+示例：给序列化输出的值添加自定义后缀的注解类
+
+```php
+use Astral\Serialize\Contracts\Attribute\OutputValueCastInterface;
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS)]
+class CustomerOutput implements OutputValueCastInterface
+{
+    public function __construct(
+        public string $suffix = '',
+    ) {
+    }
+    
+    public function match(mixed $value, DataCollection $collection, OutputValueContext $context): bool
+    {
+        // 对所有输出值都生效
+        return true;
+    }
+
+    public function resolve(mixed $value, DataCollection $collection, OutputValueContext $context): mixed
+    {
+        // 给输出值添加后缀
+        return $value . $this->suffix;
+    }
+}
+```
+

docs/zh/annotation/date-annotation.md

@@ -1,4 +1,4 @@
-#### 时间转换
+## 时间转换
 
 1. 格式灵活性
    支持多种输入和输出时间格式
@@ -10,7 +10,7 @@
    自动将字符串转换为 DateTime 对象
    保证类型的一致性和正确性
 
-##### 基础使用
+### 基础使用
 
 ```php
 use Astral\Serialize\Attributes\Input\InputDateFormat;
@@ -57,7 +57,7 @@ $orderArray = $order->toArray();
 // ]
 ```
 
-##### 带时区的时间转换
+### 带时区的时间转换
 
 ```php
 

docs/zh/annotation/group-annotation.md

@@ -1,8 +1,8 @@
-#### 属性分组
+## 属性分组
 
 属性分组提供了一种灵活的方式来控制属性的输入和输出行为，允许在不同场景下精细地管理数据转换。
 
-##### 基本用法
+### 基本用法
 
 在属性上使用 `#[Groups]` 注解来指定属性所属的分组。
 
@@ -148,7 +148,7 @@ $multiGroupArray = $user4->toArray();
 // ]
 ```
 
-##### 嵌套类指定Group类展示
+### 嵌套类指定Group类展示
 
 ```php
 class ComplexUser extends Serialize {

docs/zh/annotation/ignore-annotation.md

@@ -1,4 +1,4 @@
-#### 字段忽略
+## 字段忽略
 
 1. **安全性控制**
     - 防止敏感信息的意外泄露
@@ -12,7 +12,7 @@
     - 减少不必要字段的序列化开销
     - 精简数据传输
 
-##### 基础使用
+### 基础使用
 
 ```php
 use Astral\Serialize\Attributes\InputIgnore;
@@ -51,7 +51,7 @@ $userArray = $user->toArray();
 // ]
 ```
 
-##### 分组忽略
+### 分组忽略
 
 忽略分组需要搭配Groups注解一起使用
 

docs/zh/annotation/mapper-annotation.md

@@ -1,4 +1,6 @@
-##### Mapper映射
+### Mapper映射
+
+### 属性映射
 
 ```php
 use Astral\Serialize\Attributes\InputName;
@@ -46,7 +48,7 @@ $userArray = $user->toArray();
 // ]
 ```
 
-##### 全局类映射
+### 全局类映射
 
 ```php
 use Astral\Serialize\Attributes\InputName;
@@ -88,33 +90,7 @@ $userArray = $user->toArray();
 // ]
 ```
 
-###### 属性映射大于类级映射
-
-```php
-
-#[InputName(SnakeCaseMapper::class)]
-class PartialOverrideUser extends Serialize {
-    #[InputName(PascalCaseMapper::class)]
-    public string $userName;  // 优先使用帕斯卡命名映射
-    
-    public string $userEmail;  // 继续使用类级别的全局映射
-}
-
-$partialUser = PartialOverrideUser::from([
-    'User_name' => '张三',     // 使用蛇形映射
-    'UserName' => '李四',     // 使用帕斯卡映射
-    'user_email' => 'user@example.com' // 使用蛇形映射
-]);
-
-$partialUser->toArray();
-// $partialUser 的内容:
-// [
-//     'userName' => '李四',
-//     'userEmail' => 'user@example.com',
-// ]
-```
-
-###### 全局类映射的分组使用
+### 全局类映射的分组使用
 
 需要搭配`Groups`注解一起使用
 
@@ -180,7 +156,7 @@ $complexUser = $complexUser->toArray();
 //     'userEmail' => 张三,
 // ]
 ```
-#### 自定义映射器
+### 自定义映射器
 
 ```php
 // 自定义映射器 需要继承NameMapper 并实现 resolve
@@ -195,4 +171,30 @@ class AdvancedUser extends Serialize {
     #[InputName(CustomMapper::class)]
     public string $name;
 }
+```
+
+### Tips：属性映射优先于类级映射
+
+```php
+
+#[InputName(SnakeCaseMapper::class)]
+class PartialOverrideUser extends Serialize {
+    #[InputName(PascalCaseMapper::class)]
+    public string $userName;  // 优先使用帕斯卡命名映射
+    
+    public string $userEmail;  // 继续使用类级别的全局映射
+}
+
+$partialUser = PartialOverrideUser::from([
+    'User_name' => '张三',     // 使用蛇形映射
+    'UserName' => '李四',     // 使用帕斯卡映射
+    'user_email' => 'user@example.com' // 使用蛇形映射
+]);
+
+$partialUser->toArray();
+// $partialUser 的内容:
+// [
+//     'userName' => '李四',
+//     'userEmail' => 'user@example.com',
+// ]
 ```

docs/zh/faker/collection-faker.md

@@ -1,4 +1,4 @@
-### 集合模拟
+## 集合模拟
 
 ```php
 

docs/zh/faker/method-faker.md

@@ -1,4 +1,6 @@
-### Faker类方法模拟
+## Faker类方法模拟
+
+### 基本用法
 
 ```php
 class UserService {
@@ -13,7 +15,7 @@ class UserFaker extends Serialize {
 }
 ```
 
-#### 完整的示例
+### 完整的示例
 
 ```php
 use Astral\Serialize\Serialize;