From fc7e0e633db9e6f9776a97ab740ad70d34a6d0ac Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Mon, 31 Aug 2026 14:45:01 +0100 Subject: [PATCH] refactor(spec): honour the declared type in the OpenAPI3 parameter default Rather than adding one more class to the object case, the default branch now emits an object when the validator reports TYPE_OBJECT, so the next object validator without a case of its own does not regress the same way. The listed cases keep their current behaviour: Assoc reports TYPE_ARRAY but is deliberately published as an object, and a type-driven rule applied to them would change that. Across the full cloud route table this changes exactly the two FCM parameters and nothing else. --- .../SDK/Specification/Format/OpenAPI3.php | 12 +++- tests/unit/SDK/Specification/FormatTest.php | 60 ++++++++++++++++++- 2 files changed, 69 insertions(+), 3 deletions(-) diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index 53151e610c..4410385545 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -733,7 +733,6 @@ class OpenAPI3 extends Format break; case \Utopia\Validator\JSON::class: case \Utopia\Validator\JSON\ObjectValidator::class: - case \Utopia\Validator\JSON\FCM::class: case \Utopia\Validator\Assoc::class: $node['schema']['type'] = 'object'; $node['schema']['default'] = (empty($param['default'])) ? new \stdClass() : $param['default']; @@ -944,6 +943,17 @@ class OpenAPI3 extends Format } break; default: + // The cases above match on the concrete validator class, so a + // validator that declares itself an object but is not listed + // reaches here and would be published as a string. That is how + // JSON\FCM narrowed serviceAccountJSON in every generated SDK. + if ($validator->getType() === Validator::TYPE_OBJECT) { + $node['schema']['type'] = 'object'; + $node['schema']['default'] = empty($param['default']) ? new \stdClass() : $param['default']; + $node['schema']['example'] = ($param['example'] ?? '') !== '' ? $param['example'] : '{}'; + break; + } + $node['schema']['type'] = 'string'; if (($param['example'] ?? '') !== '') { $node['schema']['example'] = $param['example']; diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index 5601a70c1d..c4424d7c0d 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -54,6 +54,7 @@ use Utopia\Database\Validator\Spatial; use Utopia\DI\Container; use Utopia\Http\Route; use Utopia\Platform\Enum; +use Utopia\Validator; use Utopia\Validator\AnyOf; use Utopia\Validator\ArrayList; use Utopia\Validator\Assoc; @@ -69,6 +70,56 @@ use Utopia\Validator\Range; use Utopia\Validator\Text; use Utopia\Validator\WhiteList; +/** + * Stands in for a validator that reports an object but has no case of its own in + * the OpenAPI3 parameter switch, which is the shape that regressed. + */ +class UnlistedObjectValidator extends Validator +{ + public function getDescription(): string + { + return 'Value must be an object'; + } + + public function isArray(): bool + { + return false; + } + + public function getType(): string + { + return self::TYPE_OBJECT; + } + + public function isValid(mixed $value): bool + { + return \is_array($value) || $value instanceof \stdClass; + } +} + +class UnlistedStringValidator extends Validator +{ + public function getDescription(): string + { + return 'Value must be a string'; + } + + public function isArray(): bool + { + return false; + } + + public function getType(): string + { + return self::TYPE_STRING; + } + + public function isValid(mixed $value): bool + { + return \is_string($value); + } +} + class TestFormat extends Format { public function getName(): string @@ -1041,7 +1092,7 @@ final class FormatTest extends TestCase $this->assertSame('object', $openApiQuery['type']); } - public function testObjectValidatorsOutsideTheSwitchAreNotEmittedAsStrings(): void + public function testObjectValidatorsWithoutTheirOwnCaseAreNotEmittedAsStrings(): void { Method::$processed = []; Method::$errors = []; @@ -1057,13 +1108,18 @@ final class FormatTest extends TestCase responses: [], )) ->param('serviceAccountJSON', null, new Nullable(new FCM()), 'FCM service account JSON.', true) - ->param('bareServiceAccountJSON', null, new FCM(), 'FCM service account JSON.', true); + ->param('bareServiceAccountJSON', null, new FCM(), 'FCM service account JSON.', true) + ->param('unlistedObject', null, new UnlistedObjectValidator(), 'An object validator with no case of its own.', true) + ->param('unlistedString', null, new UnlistedStringValidator(), 'A string validator with no case of its own.', true); $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); $properties = $spec['paths']['/tests/fcm']['post']['requestBody']['content']['application/json']['schema']['properties']; $this->assertSame('object', $properties['serviceAccountJSON']['type']); $this->assertSame('object', $properties['bareServiceAccountJSON']['type']); + $this->assertSame('object', $properties['unlistedObject']['type']); + $this->assertEquals(new \stdClass(), $properties['unlistedObject']['default']); + $this->assertSame('string', $properties['unlistedString']['type']); } public function testJsonAndNullableModelRulesEmitExpectedSchemas(): void