From 7beb124a4767463177968baa102cf9bed19cebb2 Mon Sep 17 00:00:00 2001
From: Julien Duseyau <julien.duseyau@gmail.com>
Date: Tue, 5 Aug 2025 11:53:30 +0200
Subject: [PATCH 1/2] test: add parameter-level schema definition override
 scenario

---
 tests/Fixtures/Utils/SchemaGeneratorFixture.php | 13 +++++++++++++
 tests/Integration/SchemaGenerationTest.php      | 13 +++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/tests/Fixtures/Utils/SchemaGeneratorFixture.php b/tests/Fixtures/Utils/SchemaGeneratorFixture.php
index 34a5605..db8373b 100644
--- a/tests/Fixtures/Utils/SchemaGeneratorFixture.php
+++ b/tests/Fixtures/Utils/SchemaGeneratorFixture.php
@@ -397,4 +397,17 @@ public function parameterSchemaInferredType(
         $inferredParam
     ): void {
     }
+
+    /**
+     * Parameter with complete custom definition via #[Schema(definition: ...)]
+     */
+    public function parameterWithRawDefinition(
+        #[Schema(definition: [
+            'description' => 'Custom-defined schema',
+            'type' => 'string',
+            'format' => 'uuid'
+        ])]
+        string $custom
+    ): void {
+    }
 }
diff --git a/tests/Integration/SchemaGenerationTest.php b/tests/Integration/SchemaGenerationTest.php
index f40b936..9cf7215 100644
--- a/tests/Integration/SchemaGenerationTest.php
+++ b/tests/Integration/SchemaGenerationTest.php
@@ -354,3 +354,16 @@
 
     expect($schema['required'])->toEqual(['inferredParam']);
 });
+
+it('uses raw parameter-level schema definition as-is', function () {
+    $method = new ReflectionMethod(SchemaGeneratorFixture::class, 'parameterWithRawDefinition');
+    $schema = $this->schemaGenerator->generate($method);
+
+    expect($schema['properties']['custom'])->toEqual([
+        'description' => 'Custom-defined schema',
+        'type' => 'string',
+        'format' => 'uuid'
+    ]);
+
+    expect($schema['required'])->toEqual(['custom']);
+});

From 5b1087a40f93b850edc011cfa3a6eb93fa2a3c45 Mon Sep 17 00:00:00 2001
From: Julien Duseyau <julien.duseyau@gmail.com>
Date: Tue, 5 Aug 2025 11:54:51 +0200
Subject: [PATCH 2/2] fix: handle parameter-level schema definition override in
 buildParameterSchema

---
 src/Utils/SchemaGenerator.php | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/Utils/SchemaGenerator.php b/src/Utils/SchemaGenerator.php
index c896d9d..874dbdd 100644
--- a/src/Utils/SchemaGenerator.php
+++ b/src/Utils/SchemaGenerator.php
@@ -183,6 +183,10 @@ private function buildParameterSchema(array $paramInfo, ?array $methodLevelParam
         // Parameter-level takes highest precedence
         $parameterLevelSchema = $paramInfo['parameter_schema'];
         if (!empty($parameterLevelSchema)) {
+            if (isset($parameterLevelSchema['definition']) && is_array($parameterLevelSchema['definition'])) {
+                return $parameterLevelSchema['definition'];
+            }
+
             $mergedSchema = $this->mergeSchemas($mergedSchema, $parameterLevelSchema);
         }