RC1

astral-data · astral-data · commit ab7f5d1102dc · 2025-06-12T15:21:16.000+08:00
diff --git a/src/OpenApi/Collections/OpenApiCollection.php b/src/OpenApi/Collections/OpenApiCollection.php
@@ -105,19 +105,23 @@ public function buildRequestBodyParameterCollections(string $className, array $g
         $serializeContext->from();
         $properties = $serializeContext->getGroupCollection()->getProperties();
 
+
         $vols = [];
         foreach ($properties as $property){
             $vol = new ParameterCollection(
+                className: $className,
                 name: current($property->getInputNamesByGroups($groups,$className)),
                 descriptions: '',
+                types: $property->getTypes(),
                 type: ParameterTypeEnum::getByTypes($property->getTypes()),
                 required: !$property->isNullable(),
                 ignore: false,
             );
 
             if($property->getChildren()){
                 foreach ($property->getChildren() as $children){
-                    $vol->children[] = $this->buildRequestBodyParameterCollections($children->getClassName());
+                    $className = $children->getClassName();
+                    $vol->children[$className] = $this->buildRequestBodyParameterCollections($className);
                 }
             }
 
@@ -144,16 +148,18 @@ public function buildResponseParameterCollections(): array
             return  [];
         }
 
-        $groups = $this->response ? $this->response->groups : ['default'];
+        $groups = $this->response && is_array($this->response->groups) ?  $this->response->groups : ['default'];
         $serializeContext =  ContextFactory::build($responseClass);
         $serializeContext->from();
         $properties = $serializeContext->getGroupCollection()->getProperties();
 
         $vols = [];
         foreach ($properties as $property){
             $vol  =  new  ParameterCollection(
+                className: $responseClass,
                 name:current($property->getOutNamesByGroups($groups,$responseClass)),
                 descriptions: '',
+                types: $property->getTypes(),
                 type: ParameterTypeEnum::getByTypes($property->getTypes()),
                 required: !$property->isNullable(),
                 ignore: false,
diff --git a/src/OpenApi/Collections/ParameterChildrenCollection.php b/src/OpenApi/Collections/ParameterChildrenCollection.php
@@ -0,0 +1,17 @@
+<?php
+
+namespace Astral\Serialize\OpenApi\Collections;
+
+
+use Astral\Serialize\OpenApi\Enum\ParameterTypeEnum;
+
+class ParameterChildrenCollection
+{
+    public function __construct(
+        public ParameterTypeEnum $type = ParameterTypeEnum::STRING,
+        /** @var array<int, ParameterCollection[]> $children */
+        public array             $children = [],
+    )
+    {
+    }
+}
diff --git a/src/OpenApi/Collections/ParameterCollection.php b/src/OpenApi/Collections/ParameterCollection.php
@@ -6,24 +6,37 @@
 
 use Astral\Serialize\Enums\TypeKindEnum;
 use Astral\Serialize\OpenApi\Enum\ParameterTypeEnum;
+use Astral\Serialize\Support\Collections\TypeCollection;
 use Attribute;
 
 class ParameterCollection
 {
     public function __construct(
+        public string $className,
         /** @var string 元素变量名 */
         public string       $name,
         /** @var string descriptions  */
         public string       $descriptions = '',
-        public ParameterTypeEnum $type = ParameterTypeEnum::STRING,
+        /** @var TypeCollection[] $types */
+        public array $types,
+        public ParameterTypeEnum $type,
         /** @var mixed 示例值 */
         public mixed        $example = '',
         /** @var bool 是否必填 */
         public bool         $required = false,
         /** @var bool 是否忽略显示 */
         public bool         $ignore = false,
-        /** @var array<string, ParameterCollection> $children */
+        /** @var array<ParameterCollection[]> $children */
         public array        $children  = [],
     ){
     }
+
+    public function addChildren(array $collections,ParameterTypeEnum $type = ParameterTypeEnum::STRING): void
+    {
+        $children = new ParameterChildrenCollection();
+        $children->type = $type;
+        $children->children = $collections;
+        $this->children[] = $children;
+    }
 }
+
diff --git a/src/OpenApi/Enum/ParameterTypeEnum.php b/src/OpenApi/Enum/ParameterTypeEnum.php
@@ -17,6 +17,56 @@ enum ParameterTypeEnum: string
     case ANY_OF = 'anyOf';
     case ALL_OF = 'allOf';
 
+    public function isObject(): bool
+    {
+        return $this === self::OBJECT;
+    }
+
+    public function isArray(): bool
+    {
+        return $this === self::ARRAY;
+    }
+
+    public function isOf(): bool
+    {
+        return $this === self::ONE_OF ||  $this === self::ANY_OF || $this === self::ALL_OF;
+    }
+
+    public static function getBaseEnumByTypeKindEnum(TypeCollection $collection, string $className = null): ?ParameterTypeEnum
+    {
+        return match (true){
+            $collection->kind === TypeKindEnum::STRING && !$className => self::STRING,
+            $collection->kind === TypeKindEnum::INT && !$className => self::INTEGER,
+            $collection->kind === TypeKindEnum::FLOAT && !$className => self::NUMBER,
+            $collection->kind === TypeKindEnum::BOOLEAN  && !$className=> self::BOOLEAN,
+            in_array($collection->kind, [TypeKindEnum::CLASS_OBJECT, TypeKindEnum::OBJECT], true) && $className === $collection->className => self::OBJECT,
+            in_array($collection->kind, [TypeKindEnum::ARRAY, TypeKindEnum::COLLECT_SINGLE_OBJECT, TypeKindEnum::COLLECT_UNION_OBJECT], true) && $className === $collection->className => self::ARRAY,
+            default => null,
+        };
+    }
+
+    /**
+     * @param TypeCollection[] $types
+     * @param string $className
+     * @return ParameterTypeEnum|null
+     */
+
+    public static function getArrayAndObjectEnumBy(array $types, string $className): ?ParameterTypeEnum
+    {
+
+        foreach ($types as $collection){
+            if($className === $collection->className && in_array($collection->kind, [TypeKindEnum::CLASS_OBJECT, TypeKindEnum::OBJECT], true)){
+                return self::OBJECT;
+            }
+
+            if( $className === $collection->className && in_array($collection->kind, [TypeKindEnum::ARRAY, TypeKindEnum::COLLECT_SINGLE_OBJECT, TypeKindEnum::COLLECT_UNION_OBJECT], true)){
+                return self::ARRAY;
+            }
+        }
+
+        return null;
+    }
+
     /**
      * @param TypeCollection[] $types
      */
diff --git a/src/OpenApi/Storage/OpenAPI/SchemaStorage.php b/src/OpenApi/Storage/OpenAPI/SchemaStorage.php
@@ -5,92 +5,154 @@
 namespace Astral\Serialize\OpenApi\Storage\OpenAPI;
 
 use Astral\Serialize\OpenApi\Collections\ParameterCollection;
+use Astral\Serialize\OpenApi\Enum\ParameterTypeEnum;
 use Astral\Serialize\OpenApi\Storage\StorageInterface;
-use Exception;
 
 /**
- * 文档开发者介绍
+ * OpenAPI Schema 数据存储和构建器
+ * 用于生成符合 OpenAPI 规范的 Schema 结构
  */
 class SchemaStorage implements StorageInterface
 {
-    private array|SchemaStorage $data = [
+    /**
+     * Schema 数据结构
+     */
+    private array $data = [
         'type'       => 'object',
         'properties' => [],
     ];
 
-    public function getData(): SchemaStorage|array
+    /**
+     * 获取构建的 Schema 数据
+     */
+    public function getData(): array
     {
         return $this->data;
     }
 
     /**
-     * Undocumented function
+     * 构建 OpenAPI Schema 数据结构
      *
-     * @param array<string,ParameterCollection> $tree
-     * @param mixed|null $node
-     * @return SchemaStorage
+     * @param array<ParameterCollection> $parameterTree 参数集合树
+     * @param array|null $currentNode 当前构建节点的引用
+     * @return static
      */
-    public function build(array $tree, mixed &$node = null): static
+    public function build(array $parameterTree, array &$currentNode = null): static
     {
-        if ($node === null) {
-            $node = &$this->data;
+        if ($currentNode === null) {
+            $currentNode = &$this->data;
         }
 
-        foreach ($tree as $item) {
+        foreach ($parameterTree as $parameter) {
+
 
-            if ($item->ignore) {
+            // 跳过被标记为忽略的参数
+            if ($parameter->ignore) {
                 continue;
             }
 
-            $node['properties'][$item->name] = [
-                'type'        => strtolower($item->type->getOpenApiName()),
-                'description' => $item->descriptions,
-                'example'     => $item->example,
-            ];
+            // 构建基础属性 Schema
+            $this->buildBasicPropertySchema($parameter, $currentNode);
 
-            if ($item->required) {
-                $node['required'][] = $item->name;
+            // oneOf/anyOf/allOf 格式
+            if($parameter->type->isOf()){
+                $this->buildOfProperties($parameter, $currentNode);
+            }
+            // 处理嵌套子属性
+            else if ($parameter->children) {
+                $this->buildNestedProperties($parameter, $currentNode);
             }
+        }
 
-            if ($item->children) {
-                // list对象
-                if ($item->type->isCollect()) {
-                    $node['properties'][$item->name]['items'] = [
-                        'type'       => 'object',
-                        'properties' => [],
-                    ];
-                    $tree = &$node['properties'][$item->name]['items'];
-                }
-                // 单个对象
-                elseif ($item->type->existsCollectClass()) {
-                    $node['properties'][$item->name] = [
-                        'type'       => 'object',
-                        'properties' => [],
-                    ];
-                    $tree = &$node['properties'][$item->name];
-                }
+        return $this;
+    }
+
+    /**
+     * 构建基础属性的 Schema 结构
+     */
+    private function buildBasicPropertySchema(ParameterCollection $parameter, array &$currentNode): void
+    {
+        $propertyName = $parameter->name;
+
+        $currentNode['properties'][$propertyName] = [
+            'type'        => $parameter->type->value,
+            'description' => $parameter->descriptions,
+            'example'     => $parameter->example,
+        ];
 
-                foreach ($item->children as $v){
-                    $this->build($v, $tree);
+        // 添加必填字段标记
+        if ($parameter->required) {
+            $currentNode['required'][] = $propertyName;
+        }
+    }
+
+    /**
+     * 构建 oneOf/anyOf/allOf 属性结构
+     */
+    public function buildOfProperties(ParameterCollection $topParameter, array &$currentNode): void
+    {
+        $propertyName = $topParameter->name;
+        // 重构属性结构为 oneOf/anyOf/allOf 格式
+        $node = &$currentNode['properties'][$propertyName][$topParameter->type->value];
+
+        $i = 0;
+        foreach ($topParameter->types as $kindType){
+            $type = ParameterTypeEnum::getBaseEnumByTypeKindEnum($kindType);
+            if($type){
+                $node[$i] = ['type'=> $type];
+                $i++;
+            }
+        }
+
+        if($topParameter->children){
+            foreach ($topParameter->children as $className => $child){
+                $type = ParameterTypeEnum::getArrayAndObjectEnumBy($topParameter->types,$className);
+                if($type->isObject()){
+                    $node[$i] = ['type'=>'object','properties' => []];
+                    $childNode = &$node[$i];
+                    $i++;
+                }else if($type->isArray()){
+                    $node[$i] = ['type'=>'array','items'=> ['type'=>'object','properties' => []]];
+                    $childNode = &$node[$i]['items'];
+                    $i++;
                 }
 
+                $this->build($child,$childNode);
             }
         }
 
-        return $this;
     }
 
-    public function addProperties(string $name, string $type, string $description, string $example, bool $required = false): void
+    /**
+     * 构建嵌套属性结构
+     */
+    private function buildNestedProperties(ParameterCollection $topParameter, array &$currentNode): void
     {
-        $this->data['properties'][$name] = [
-            'type'        => $type,
-            'description' => $description,
-            'example'     => $example,
-        ];
+        $propertyName = $topParameter->name;
+        $nestedNode = null;
+
+        if ($topParameter->type->isArray()) {
+            // 数组类型：创建 items 结构
+            $currentNode['properties'][$propertyName]['items'] = [
+                'type'       => 'object',
+                'properties' => [],
+            ];
+            $nestedNode = &$currentNode['properties'][$propertyName]['items'];
+        } elseif ($topParameter->type->isObject()) {
+            // 对象类型：重构为嵌套对象结构
+            $currentNode['properties'][$propertyName] = [
+                'type'       => 'object',
+                'properties' => [],
+                'description' => $topParameter->descriptions,
+            ];
+            $nestedNode = &$currentNode['properties'][$propertyName];
+        }
 
-        if ($required) {
-            $this->data['required'][] = $name;
+        // 递归构建子属性
+        if ($nestedNode !== null) {
+            foreach ($topParameter->children as $childParameter) {
+                $this->build($childParameter, $nestedNode);
+            }
         }
     }
-
-}
+}
diff --git a/tests/Openapi/OpenApi.php b/tests/Openapi/OpenApi.php
