From 3585d982ffeaa1ef13f0c03c1452a49eb362c3ea Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 28 Jul 2026 00:19:33 +0530 Subject: [PATCH] fix(specs): normalise every Queries validator to an array type The OpenAPI3 format matched validators on an exact get_class(), normalising only Queries\Base subclasses. Any validator extending Utopia's Queries directly had to be enumerated by hand, so a missing entry silently fell through to the default branch and emitted "type": "string" with a "default" of []. VcsRepositories hit exactly that: vcsListRepositories advertised its queries parameter as a string, which made the CLI generator drop --limit, --offset and --filter and degrade --queries to a single value. Branches only escaped because someone remembered to list it. Normalise the whole hierarchy with is_subclass_of instead, which collapses the 30-case group to one and stops the next Queries subclass from breaking its SDK surface unnoticed. --- .../SDK/Specification/Format/OpenAPI3.php | 42 +++---------------- tests/unit/SDK/Specification/FormatTest.php | 40 ++++++++++++++++++ 2 files changed, 46 insertions(+), 36 deletions(-) diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index 06759c1359..04095bc23b 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -16,6 +16,7 @@ use Appwrite\Utopia\Response\Model\Any; use Utopia\Database\Database; use Utopia\Database\Helpers\Permission; use Utopia\Database\Helpers\Role; +use Utopia\Database\Validator\Queries; use Utopia\Database\Validator\Spatial; use Utopia\Platform\Enum; use Utopia\Validator; @@ -456,12 +457,10 @@ class OpenAPI3 extends Format $class = \get_class($validator); - $base = \get_parent_class($class); - - switch ($base) { - case \Appwrite\Utopia\Database\Validator\Queries\Base::class: - $class = $base; - break; + // Every Queries validator serialises to an array of query strings, so + // normalise the whole hierarchy instead of enumerating each subclass. + if (\is_subclass_of($class, Queries::class)) { + $class = Queries::class; } if ($class === \Utopia\Validator\AnyOf::class) { @@ -588,36 +587,7 @@ class OpenAPI3 extends Format $node['schema']['x-example'] = $param['example']; } break; - case \Appwrite\Utopia\Database\Validator\Queries\Base::class: - case \Appwrite\Utopia\Database\Validator\Queries\Columns::class: - case \Appwrite\Utopia\Database\Validator\Queries\Attributes::class: - case \Appwrite\Utopia\Database\Validator\Queries\Buckets::class: - case \Appwrite\Utopia\Database\Validator\Queries\Tables::class: - case \Appwrite\Utopia\Database\Validator\Queries\Collections::class: - case \Appwrite\Utopia\Database\Validator\Queries\Databases::class: - case \Appwrite\Utopia\Database\Validator\Queries\Deployments::class: - case \Appwrite\Utopia\Database\Validator\Queries\Executions::class: - case \Appwrite\Utopia\Database\Validator\Queries\Files::class: - case \Appwrite\Utopia\Database\Validator\Queries\Functions::class: - case \Appwrite\Utopia\Database\Validator\Queries\Identities::class: - case \Appwrite\Utopia\Database\Validator\Queries\Indexes::class: - case \Appwrite\Utopia\Database\Validator\Queries\Installations::class: - case \Appwrite\Utopia\Database\Validator\Queries\Branches::class: - case \Appwrite\Utopia\Database\Validator\Queries\Memberships::class: - case \Appwrite\Utopia\Database\Validator\Queries\Messages::class: - case \Appwrite\Utopia\Database\Validator\Queries\Migrations::class: - case \Appwrite\Utopia\Database\Validator\Queries\Projects::class: - case \Appwrite\Utopia\Database\Validator\Queries\Providers::class: - case \Appwrite\Utopia\Database\Validator\Queries\Rules::class: - case \Appwrite\Utopia\Database\Validator\Queries\Subscribers::class: - case \Appwrite\Utopia\Database\Validator\Queries\Targets::class: - case \Appwrite\Utopia\Database\Validator\Queries\Teams::class: - case \Appwrite\Utopia\Database\Validator\Queries\Topics::class: - case \Appwrite\Utopia\Database\Validator\Queries\Users::class: - case \Appwrite\Utopia\Database\Validator\Queries\Variables::class: - case \Utopia\Database\Validator\Queries::class: - case \Utopia\Database\Validator\Queries\Document::class: - case \Utopia\Database\Validator\Queries\Documents::class: + case Queries::class: $node['schema']['type'] = 'array'; $node['schema']['items'] = [ 'type' => 'string', diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index e91424b885..f3542188e1 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -10,6 +10,7 @@ use Appwrite\SDK\Specification\Format; use Appwrite\SDK\Specification\Format\OpenAPI3; use Appwrite\SDK\Specification\Validator\PasswordFormat; use Appwrite\Utopia\Database\Validator\CustomId; +use Appwrite\Utopia\Database\Validator\Queries\VcsRepositories; use Appwrite\Utopia\Response; use Appwrite\Utopia\Response\Model\AlgoArgon2; use Appwrite\Utopia\Response\Model\AlgoBcrypt; @@ -35,6 +36,9 @@ use Appwrite\Utopia\Response\Model\User; use Appwrite\Utopia\Response\Model\Webhook; use PHPUnit\Framework\TestCase; use Utopia\Database\Database; +use Utopia\Database\Validator\Queries; +use Utopia\Database\Validator\Query\Limit; +use Utopia\Database\Validator\Query\Offset; use Utopia\Database\Validator\Spatial; use Utopia\DI\Container; use Utopia\Http\Route; @@ -602,4 +606,40 @@ final class FormatTest extends TestCase $this->assertTrue($openApiOptions['additionalProperties']); $this->assertArrayNotHasKey('nullable', $openApiOptions); } + + public function testQueriesSubclassesEmitArrayOfStrings(): void + { + Method::$processed = []; + Method::$errors = []; + + // VcsRepositories extends Queries directly rather than Queries\Base, and a + // deeper subclass proves arbitrary inheritance depth is normalised too. + $deepSubclass = new class () extends VcsRepositories {}; + + $route = (new Route('GET', '/v1/tests/queries')) + ->desc('List tests') + ->label('sdk', new Method( + namespace: 'test', + group: null, + name: 'listTests', + description: 'List tests.', + auth: [], + responses: [], + )) + ->param('queries', [], new Queries([new Limit(), new Offset()]), 'Queries.', true) + ->param('repositoryQueries', [], new VcsRepositories(), 'Repository queries.', true) + ->param('deepQueries', [], $deepSubclass, 'Deeply nested queries.', true); + + $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + + $parameters = $openApi['paths']['/tests/queries']['get']['parameters']; + $schemas = \array_column($parameters, 'schema', 'name'); + + $this->assertCount(3, $schemas); + + foreach (['queries', 'repositoryQueries', 'deepQueries'] as $name) { + $this->assertSame('array', $schemas[$name]['type'], "{$name} must serialise as an array"); + $this->assertSame(['type' => 'string'], $schemas[$name]['items'], "{$name} must hold query strings"); + } + } }