Added support for extra metadata reflected in the OpenApiSpecification (#1811)

Author: norberttech

documentation/components/bridges/openapi-specification-bridge.md

@@ -24,19 +24,19 @@ This bridge allows you to convert Flow PHP schemas to OpenAPI specification form
 
 use function Flow\ETL\DSL\{schema, int_schema, str_schema, bool_schema};
 use function Flow\Bridge\OpenAPI\Specification\DSL\schema_to_openapi_specification;
-use Flow\ETL\Schema\Metadata;
+use Flow\Bridge\OpenAPI\Specification\OpenAPIMetadata;
 
 $userSchema = schema(
-    int_schema('id', false, Metadata::empty()
-        ->add('description', 'Unique user identifier')
-        ->add('example', 123)
+    int_schema('id', false, 
+        OpenAPIMetadata::description('Unique user identifier')
+            ->merge(OpenAPIMetadata::example(123))
     ),
-    str_schema('name', true, Metadata::empty()
-        ->add('description', 'User full name')
-        ->add('example', 'John Doe')
+    str_schema('name', true, 
+        OpenAPIMetadata::description('User full name')
+            ->merge(OpenAPIMetadata::example('John Doe'))
     ),
-    bool_schema('active', false, Metadata::empty()
-        ->add('description', 'Account status')
+    bool_schema('active', false, 
+        OpenAPIMetadata::description('Account status')
     )
 );
 
@@ -106,6 +106,155 @@ $flowSchema = schema_from_openapi_specification($openApiSpec);
 ```
 
 
+## OpenAPI Metadata
+
+The OpenAPI Specification Bridge provides specialized metadata handling through the `OpenAPIMetadata` enum, allowing you to add OpenAPI-specific properties to your Flow schema definitions. This metadata is used during schema conversion to generate rich OpenAPI specifications.
+
+### Available OpenAPI Metadata
+
+The `OpenAPIMetadata` enum provides the following metadata types:
+
+- `DESCRIPTION` - Human-readable description of the property
+- `FORMAT` - OpenAPI format specification (e.g., 'email', 'date-time', 'uuid')
+- `EXAMPLE` - Example value for the property
+- `EXAMPLES` - Multiple named examples
+- `DEPRECATED` - Mark property as deprecated
+- `TITLE` - Short title for the property
+- `DEFAULT` - Default value for the property
+- `READ_ONLY` - Mark property as read-only
+- `WRITE_ONLY` - Mark property as write-only
+- `NULLABLE` - Override schema nullability
+
+### Using OpenAPI Metadata
+
+```php
+<?php
+
+use function Flow\ETL\DSL\{schema, int_schema, str_schema};
+use Flow\Bridge\OpenAPI\Specification\{OpenAPIConverter, OpenAPIMetadata};
+
+$userSchema = schema(
+    int_schema('id', false, 
+        OpenAPIMetadata::description('Unique user identifier')
+            ->merge(OpenAPIMetadata::format('int64'))
+            ->merge(OpenAPIMetadata::example(12345))
+            ->merge(OpenAPIMetadata::readOnly())
+    ),
+    str_schema('email', false,
+        OpenAPIMetadata::description('User email address')
+            ->merge(OpenAPIMetadata::format('email'))
+            ->merge(OpenAPIMetadata::example('user@example.com'))
+            ->merge(OpenAPIMetadata::title('Email Address'))
+    ),
+    str_schema('password', false,
+        OpenAPIMetadata::description('User password')
+            ->merge(OpenAPIMetadata::format('password'))
+            ->merge(OpenAPIMetadata::writeOnly())
+    ),
+    str_schema('status', false,
+        OpenAPIMetadata::description('Account status')
+            ->merge(OpenAPIMetadata::default('active'))
+            ->merge(OpenAPIMetadata::examples([
+                'active' => 'active',
+                'inactive' => 'inactive',
+                'suspended' => 'suspended'
+            ]))
+    )
+);
+
+$converter = new OpenAPIConverter();
+$openApiSpec = $converter->toOpenAPI($userSchema);
+
+// Results in:
+// [
+//     'type' => 'object',
+//     'properties' => [
+//         'id' => [
+//             'type' => 'integer',
+//             'nullable' => false,
+//             'description' => 'Unique user identifier',
+//             'format' => 'int64',
+//             'example' => 12345,
+//             'readOnly' => true
+//         ],
+//         'email' => [
+//             'type' => 'string',
+//             'nullable' => false,
+//             'description' => 'User email address',
+//             'format' => 'email',
+//             'example' => 'user@example.com',
+//             'title' => 'Email Address'
+//         ],
+//         'password' => [
+//             'type' => 'string',
+//             'nullable' => false,
+//             'description' => 'User password',
+//             'format' => 'password',
+//             'writeOnly' => true
+//         ],
+//         'status' => [
+//             'type' => 'string',
+//             'nullable' => false,
+//             'description' => 'Account status',
+//             'default' => 'active',
+//             'examples' => [
+//                 'active' => 'active',
+//                 'inactive' => 'inactive',
+//                 'suspended' => 'suspended'
+//             ]
+//         ]
+//     ]
+// ]
+```
+
+### Metadata Priority System
+
+The OpenAPI bridge uses a priority system when handling metadata:
+
+1. **OpenAPI-specific metadata** (from `OpenAPIMetadata`) takes highest priority
+2. **Legacy metadata keys** are used as fallback when OpenAPI metadata is not present
+
+```php
+<?php
+
+use Flow\ETL\Schema\Metadata;
+use Flow\Bridge\OpenAPI\Specification\OpenAPIMetadata;
+
+// OpenAPI metadata takes priority over legacy metadata
+$metadata = Metadata::with('description', 'Legacy description')
+    ->merge(OpenAPIMetadata::description('OpenAPI description')) // This wins
+    ->merge(Metadata::with('example', 'Legacy example'))
+    ->merge(OpenAPIMetadata::example('OpenAPI example')); // This wins
+
+$schema = schema(
+    str_schema('field', false, $metadata)
+);
+
+// Result will use OpenAPI values: "OpenAPI description" and "OpenAPI example"
+```
+
+### Common OpenAPI Formats
+
+Here are some commonly used OpenAPI formats you can specify with `OpenAPIMetadata::format()`:
+
+**String formats:**
+- `email` - Email address
+- `uri` - URI/URL
+- `uuid` - UUID string
+- `date` - Date (YYYY-MM-DD)
+- `date-time` - Date and time (RFC 3339)
+- `password` - Password field
+- `byte` - Base64 encoded string
+- `binary` - Binary data
+
+**Integer formats:**
+- `int32` - 32-bit integer
+- `int64` - 64-bit integer
+
+**Number formats:**
+- `float` - Floating point number
+- `double` - Double precision number
+
 ### Usage Example
 
 ```php
@@ -114,17 +263,39 @@ $flowSchema = schema_from_openapi_specification($openApiSpec);
 use function Flow\ETL\DSL\{schema, int_schema, str_schema, list_schema, structure_schema};
 use function Flow\Types\DSL\{type_list, type_string, type_structure};
 use function Flow\Bridge\OpenAPI\Specification\DSL\schema_to_openapi_specification;
+use Flow\Bridge\OpenAPI\Specification\OpenAPIMetadata;
 
-// Define your data schema
+// Define your data schema with rich OpenAPI metadata
 $productSchema = schema(
-    int_schema('id', false),
-    str_schema('name', false),
-    str_schema('description', true),
+    int_schema('id', false, 
+        OpenAPIMetadata::description('Product identifier')
+            ->merge(OpenAPIMetadata::format('int64'))
+            ->merge(OpenAPIMetadata::example(123))
+            ->merge(OpenAPIMetadata::readOnly())
+    ),
+    str_schema('name', false,
+        OpenAPIMetadata::description('Product name')
+            ->merge(OpenAPIMetadata::title('Name'))
+            ->merge(OpenAPIMetadata::example('iPhone 15'))
+    ),
+    str_schema('description', true,
+        OpenAPIMetadata::description('Detailed product description')
+            ->merge(OpenAPIMetadata::example('Latest smartphone with advanced features'))
+    ),
     structure_schema('category', type_structure([
         'id' => type_string(),
         'name' => type_string()
-    ]), false),
-    list_schema('tags', type_list(type_string()), true)
+    ]), false, 
+        OpenAPIMetadata::description('Product category information')
+    ),
+    list_schema('tags', type_list(type_string()), true,
+        OpenAPIMetadata::description('Product tags for categorization')
+            ->merge(OpenAPIMetadata::examples([
+                'electronics' => 'electronics',
+                'smartphone' => 'smartphone',
+                'apple' => 'apple'
+            ]))
+    )
 );
 
 $apiSpec = schema_to_openapi_specification($productSchema);
@@ -157,15 +328,4 @@ $fullApiSpec = [
         ]
     ]
 ];
-```
-
-## Supported OpenAPI Features
-
-### ✅ Supported
-- Basic types (boolean, integer, number, string)
-- String formats (date, date-time, time, uuid, json, xml)
-- Arrays with typed items
-- Objects with properties and additionalProperties
-- Nullable types
-- Descriptions and examples
-- Nested structures
+```

src/bridge/openapi/specification/src/Flow/Bridge/OpenAPI/Specification/OpenAPIConverter.php

@@ -120,11 +120,51 @@ private function convertDefinitionToOpenAPI(Definition $definition) : array
         $property = $this->convertTypeToOpenAPI($definition->type());
         $property['nullable'] = $definition->isNullable();
 
-        if ($definition->metadata()->has('description')) {
+        if ($definition->metadata()->has(OpenAPIMetadata::DESCRIPTION->value)) {
+            $property['description'] = $definition->metadata()->get(OpenAPIMetadata::DESCRIPTION->value);
+        }
+
+        if ($definition->metadata()->has(OpenAPIMetadata::FORMAT->value)) {
+            $property['format'] = $definition->metadata()->get(OpenAPIMetadata::FORMAT->value);
+        }
+
+        if ($definition->metadata()->has(OpenAPIMetadata::EXAMPLE->value)) {
+            $property['example'] = $definition->metadata()->get(OpenAPIMetadata::EXAMPLE->value);
+        }
+
+        if ($definition->metadata()->has(OpenAPIMetadata::EXAMPLES->value)) {
+            $property['examples'] = $definition->metadata()->get(OpenAPIMetadata::EXAMPLES->value);
+        }
+
+        if ($definition->metadata()->has(OpenAPIMetadata::DEPRECATED->value)) {
+            $property['deprecated'] = $definition->metadata()->get(OpenAPIMetadata::DEPRECATED->value);
+        }
+
+        if ($definition->metadata()->has(OpenAPIMetadata::TITLE->value)) {
+            $property['title'] = $definition->metadata()->get(OpenAPIMetadata::TITLE->value);
+        }
+
+        if ($definition->metadata()->has(OpenAPIMetadata::DEFAULT->value)) {
+            $property['default'] = $definition->metadata()->get(OpenAPIMetadata::DEFAULT->value);
+        }
+
+        if ($definition->metadata()->has(OpenAPIMetadata::READ_ONLY->value)) {
+            $property['readOnly'] = $definition->metadata()->get(OpenAPIMetadata::READ_ONLY->value);
+        }
+
+        if ($definition->metadata()->has(OpenAPIMetadata::WRITE_ONLY->value)) {
+            $property['writeOnly'] = $definition->metadata()->get(OpenAPIMetadata::WRITE_ONLY->value);
+        }
+
+        if ($definition->metadata()->has(OpenAPIMetadata::NULLABLE->value)) {
+            $property['nullable'] = $definition->metadata()->get(OpenAPIMetadata::NULLABLE->value);
+        }
+
+        if (!isset($property['description']) && $definition->metadata()->has('description')) {
             $property['description'] = $definition->metadata()->get('description');
         }
 
-        if ($definition->metadata()->has('example')) {
+        if (!isset($property['example']) && $definition->metadata()->has('example')) {
             $property['example'] = $definition->metadata()->get('example');
         }
 
@@ -238,7 +278,6 @@ private function convertOpenAPIObjectToFlowType(array $typeSpec) : Type
             return type_map(type_string(), $valueType);
         }
 
-        // If it has properties, it's a structure
         if (isset($typeSpec['properties']) && \is_array($typeSpec['properties'])) {
             $elements = [];
             $optionalElements = [];
@@ -262,7 +301,6 @@ private function convertOpenAPIObjectToFlowType(array $typeSpec) : Type
             return type_structure($elements, $optionalElements);
         }
 
-        // Default to empty map
         return type_map(type_string(), type_string());
     }