From 46e8cc7bbac0e9db3f84e4427bc7944097eb3fe9 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Thu, 20 Aug 2026 18:15:17 +0530 Subject: [PATCH] fix(specs): keep open enums open in the generated spec (#13295) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(specs): keep open enums open in the generated spec A param declared as `AnyOf([WhiteList(...), Text(...)])` accepts any string at runtime — the whitelist names the values callers usually want and the text branch keeps everything else valid. The formatter resolved such a union by taking `getValidators()[0]` and discarding the rest, so the text branch never reached the spec. Paired with an `enum:` declaration the result advertises a closed set for a param that is deliberately open, and generated SDKs then reject values the endpoint would have accepted. Emit the union the way OpenAPI already expresses it, with `anyOf` over the enum branch and a plain string branch. That mirrors the validator exactly, so a generator can widen the parameter type while still offering the enum for discovery, and it needs no new vendor extension — the enum branch carries the same `x-enum-name` / `x-enum-keys` it does today. Strictness is derived from the validator rather than declared separately, so it cannot drift from what the endpoint actually accepts — that drift is what produced the wrong spec in the first place. No committed spec changes: the union is only emitted when an open union also declares an enum, and no param in this repository does both. * refactor(specs): simplify open enum handling * test(specs): focus open enum coverage --- .../SDK/Specification/Format/OpenAPI3.php | 52 ++++++++++++++++++- tests/unit/SDK/Specification/FormatTest.php | 33 ++++++++++++ 2 files changed, 84 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index 8c7edfdd0d..46f8a5b074 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -23,6 +23,7 @@ use Utopia\Validator; use Utopia\Validator\ArrayList; use Utopia\Validator\Nullable; use Utopia\Validator\Range; +use Utopia\Validator\WhiteList; class OpenAPI3 extends Format { @@ -533,9 +534,22 @@ class OpenAPI3 extends Format $class = Queries::class; } + $openEnum = false; if ($class === \Utopia\Validator\AnyOf::class) { - $validator = $param['validator']->getValidators()[0]; + $validators = $param['validator']->getValidators(); + $validator = $validators[0]; $class = \get_class($validator); + + foreach ($validators as $unionValidator) { + while ($unionValidator instanceof ArrayList || $unionValidator instanceof Nullable) { + $unionValidator = $unionValidator->getValidator(); + } + + if (!$unionValidator instanceof WhiteList && $unionValidator->getType() === Validator::TYPE_STRING) { + $openEnum = true; + break; + } + } } $array = false; @@ -754,6 +768,15 @@ class OpenAPI3 extends Format $node['schema']['items']['x-enum-name'] = $enum->name; } $node['schema']['items']['x-enum-keys'] = $enumKeys; + + if ($openEnum) { + $node['schema']['items'] = [ + 'anyOf' => [ + $node['schema']['items'], + ['type' => Validator::TYPE_STRING], + ], + ]; + } } } if ($validator->getType() === 'integer') { @@ -791,6 +814,26 @@ class OpenAPI3 extends Format $node['schema']['x-enum-name'] = $enum->name; } $node['schema']['x-enum-keys'] = $enumKeys; + + if ($openEnum) { + $enumBranch = ['type' => $node['schema']['type'], 'enum' => $enumValues]; + if (!empty($enum->name)) { + $enumBranch['x-enum-name'] = $enum->name; + } + $enumBranch['x-enum-keys'] = $enumKeys; + + unset( + $node['schema']['type'], + $node['schema']['enum'], + $node['schema']['x-enum-name'], + $node['schema']['x-enum-keys'], + ); + + $node['schema']['anyOf'] = [ + $enumBranch, + ['type' => Validator::TYPE_STRING], + ]; + } } } if ($validator->getType() === 'integer') { @@ -937,6 +980,13 @@ class OpenAPI3 extends Format $body['content'][$consumes[0]]['schema']['properties'][$name]['format'] = $node['schema']['format']; } + if (isset($node['schema']['anyOf'])) { + // Open enum: the known values and the free-form branch + // both live under anyOf, so copy the union wholesale. + $body['content'][$consumes[0]]['schema']['properties'][$name]['anyOf'] = $node['schema']['anyOf']; + unset($body['content'][$consumes[0]]['schema']['properties'][$name]['type']); + } + if (isset($node['schema']['enum'])) { /// If the enum flag is Set, add the enum values to the body $body['content'][$consumes[0]]['schema']['properties'][$name]['enum'] = $node['schema']['enum']; diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index 1eea5c6995..dc1cc2ed0d 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -47,6 +47,8 @@ use Utopia\Database\Validator\Query\Offset; use Utopia\Database\Validator\Spatial; use Utopia\DI\Container; use Utopia\Http\Route; +use Utopia\Platform\Enum; +use Utopia\Validator\AnyOf; use Utopia\Validator\ArrayList; use Utopia\Validator\Assoc; use Utopia\Validator\Boolean as BooleanValidator; @@ -54,6 +56,7 @@ use Utopia\Validator\JSON; use Utopia\Validator\Nullable; use Utopia\Validator\Range; use Utopia\Validator\Text; +use Utopia\Validator\WhiteList; class TestFormat extends Format { @@ -124,6 +127,36 @@ final class FormatTest extends TestCase $this->assertSame('HealthCheckStatus', (new HealthStatus())->getRules()['status']['enumSDKName']); } + public function testUnionWithAFreeStringBranchEmitsAnyOf(): void + { + Method::$processed = []; + Method::$errors = []; + + $route = (new Route('GET', '/v1/tests')) + ->desc('List tests') + ->label('sdk', new Method( + namespace: 'test', + group: null, + name: 'listTests', + description: 'List tests.', + auth: [], + responses: [], + )) + ->param('metrics', [], new AnyOf([ + new ArrayList(new WhiteList(['alpha', 'beta'], true), 10), + new ArrayList(new Text(255), 10), + ]), 'Metric names.', false, enum: new Enum(name: 'TestMetric')); + + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + + $this->assertSame([ + 'anyOf' => [ + ['type' => 'string', 'enum' => ['alpha', 'beta'], 'x-enum-name' => 'TestMetric', 'x-enum-keys' => ['alpha', 'beta']], + ['type' => 'string'], + ], + ], $spec['paths']['/tests']['get']['parameters'][0]['schema']['items']); + } + public function testOpenApiCustomIdBodyFieldIncludesIdGeneratorMetadata(): void { Method::$processed = [];