From dcadf3d7951ef484d857c2a078e2e45cc8d9b359 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Mon, 7 Sep 2026 11:04:23 +0100 Subject: [PATCH 1/3] feat: emit a canonical OpenAPI document covering every SDK platform The Specs task writes open-api3-.json alongside the per-platform files: every route any platform offers, every method alias variant, all response models, the union of tags and of security schemes. The generator selects a platform from x-appwrite.platforms since 4.8.0; what it could not select was x-appwrite.auth, whose value differs per platform, so the canonical document keys auth by platform and each security scheme lists the platforms whose SDK offers it. The per-platform documents are unchanged apart from that scheme-level platforms list, which is why they stay byte-identical for the SDKs generated from them. Related to CLO-4377. --- src/Appwrite/Platform/Tasks/Specs.php | 49 ++--- src/Appwrite/SDK/Specification/Format.php | 49 ++++- .../SDK/Specification/Format/OpenAPI3.php | 58 ++++-- tests/unit/SDK/Specification/FormatTest.php | 168 ++++++++++++++---- 4 files changed, 255 insertions(+), 69 deletions(-) diff --git a/src/Appwrite/Platform/Tasks/Specs.php b/src/Appwrite/Platform/Tasks/Specs.php index ab28b1e4c0..bb9a323212 100644 --- a/src/Appwrite/Platform/Tasks/Specs.php +++ b/src/Appwrite/Platform/Tasks/Specs.php @@ -458,10 +458,16 @@ class Specs extends Action $specsContainer->set('localeCodes', fn () => \array_map(fn ($locale) => $locale['code'], Config::getParam('locale-codes', []))); $specsContainer->set('plan', fn () => []); - $platforms = static::getPlatforms(); + $platforms = \array_values(static::getPlatforms()); $authCounts = $this->getAuthCounts(); - $keys = $this->getKeys(); + $platformKeys = $this->getKeys(); + $keys = []; + foreach ($platforms as $platform) { + $keys[$platform] = $platformKeys[$platform] ?? []; + } + + /** @var array $generatedFiles Spec file path to its platform, null for the canonical document. */ $generatedFiles = []; $endpoint = System::getEnv('_APP_HOME', 'https://appwrite.io'); $email = System::getEnv('_APP_SYSTEM_TEAM_EMAIL', 'team@appwrite.io'); @@ -483,7 +489,8 @@ class Specs extends Action } } - foreach ($platforms as $platform) { + // One document per platform, then the canonical document (null) covering every platform. + foreach ([...$platforms, null] as $platform) { $routes = []; $models = []; $services = []; @@ -506,7 +513,9 @@ class Specs extends Action } foreach ($sdks as $sdk) { - if (!\in_array($platform, $sdk->getPlatforms(), true)) { + $sdkPlatforms = $sdk->getPlatforms(); + + if ($platform === null ? $sdkPlatforms === [] : !\in_array($platform, $sdkPlatforms, true)) { continue; } @@ -541,8 +550,9 @@ class Specs extends Action continue; } - // Check if current platform is included in service's platforms - if (!\in_array($platform, $service['platforms'] ?? [])) { + $servicePlatforms = $service['platforms'] ?? []; + + if ($platform === null ? \array_intersect($servicePlatforms, $platforms) === [] : !\in_array($platform, $servicePlatforms)) { continue; } @@ -573,7 +583,7 @@ class Specs extends Action $models = $response->getModels(); foreach ($models as $key => $value) { - if ($platform !== APP_SDK_PLATFORM_CONSOLE && !$value->isPublic()) { + if ($platform !== null && $platform !== APP_SDK_PLATFORM_CONSOLE && !$value->isPublic()) { unset($models[$key]); } } @@ -583,8 +593,8 @@ class Specs extends Action $services, $routes, $models, - $keys[$platform], - $authCounts[$platform] ?? 0, + $keys, + $authCounts, $platform, ]; @@ -609,15 +619,16 @@ class Specs extends Action ->setParam('docs.description', 'Full API docs, specs and tutorials') ->setParam('docs.url', $endpoint . '/docs'); + $suffix = $platform === null ? '' : '-' . $platform; $path = $mocks - ? $specsDir . '/' . $format . '-mocks-' . $platform . '.json' - : $specsDir . '/' . $format . '-' . $version . '-' . $platform . '.json'; + ? $specsDir . '/' . $format . '-mocks' . $suffix . '.json' + : $specsDir . '/' . $format . '-' . $version . $suffix . '.json'; try { $parsedSpecs = $specs->parse(); } catch (\RuntimeException $e) { // A throw is reported and carried on from, so stop here - Console::error("Spec generation failed for {$platform} ({$format}): " . $e->getMessage()); + Console::error('Spec generation failed for ' . ($platform ?? 'canonical') . " ({$format}): " . $e->getMessage()); Console::exit(1); return; } @@ -634,7 +645,7 @@ class Specs extends Action throw new Exception('Failed to save ' . ($mocks ? 'mocks ' : '') . 'spec file: ' . $path); } - $generatedFiles[] = realpath($path); + $generatedFiles[realpath($path)] = $platform; Console::success('Saved ' . ($mocks ? 'mocks ' : '') . 'spec file: ' . realpath($path)); unset($encodedSpecs, $specs, $formatInstance); @@ -668,16 +679,12 @@ class Specs extends Action git reset --hard origin/' . $gitBranch . ' 2>/dev/null || true '); - // Copy generated spec files into specs/{version}/ subdirectory + // Copy the canonical document and the PR platforms' documents into specs/{version}/ $prPlatforms = static::getPlatformsForPR(); - $prFiles = \array_filter( + $prFiles = \array_keys(\array_filter( $generatedFiles, - fn (string $file) => \in_array( - \substr(\basename($file, '.json'), \strrpos(\basename($file, '.json'), '-') + 1), - $prPlatforms, - true - ) - ); + fn (?string $platform) => $platform === null || \in_array($platform, $prPlatforms, true) + )); $specsSubDir = $mocks ? 'mocks' : $version; \exec('mkdir -p ' . \escapeshellarg("{$target}/specs/{$specsSubDir}")); diff --git a/src/Appwrite/SDK/Specification/Format.php b/src/Appwrite/SDK/Specification/Format.php index acf8a8ea71..6935735702 100644 --- a/src/Appwrite/SDK/Specification/Format.php +++ b/src/Appwrite/SDK/Specification/Format.php @@ -22,9 +22,25 @@ abstract class Format protected array $models; protected array $services; + + /** + * Security schemes per SDK platform, in `Specs::getPlatforms()` order. + * + * @var array>> + */ protected array $keys; - protected int $authCount; - protected string $platform; + + /** + * Number of example credentials per SDK platform. + * + * @var array + */ + protected array $authCounts; + + /** + * Platform the document is filtered to, or null for the canonical document. + */ + protected ?string $platform; protected array $params = [ 'name' => '', 'description' => '', @@ -41,17 +57,42 @@ abstract class Format 'license.url' => '', ]; - public function __construct(Container $container, array $services, array $routes, array $models, array $keys, int $authCount, string $platform) + public function __construct(Container $container, array $services, array $routes, array $models, array $keys, array $authCounts, ?string $platform) { $this->container = $container; $this->services = $services; $this->routes = $routes; $this->models = $models; $this->keys = $keys; - $this->authCount = $authCount; + $this->authCounts = $authCounts; $this->platform = $platform; } + /** + * Security schemes of this document, each carrying the platforms whose SDK + * offers it: the platform's own schemes, or for the canonical document the + * union in platform order where the first definition wins. + * + * @return array> + */ + protected function getSecuritySchemes(): array + { + $schemes = []; + + foreach ($this->keys as $platform => $platformSchemes) { + if ($this->platform !== null && $platform !== $this->platform) { + continue; + } + + foreach ($platformSchemes as $name => $scheme) { + $schemes[$name] ??= $scheme; + $schemes[$name]['x-appwrite']['platforms'][] = $platform; + } + } + + return $schemes; + } + /** * Get Name. * diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index 3d758c7bb2..73354e0979 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -164,8 +164,40 @@ class OpenAPI3 extends Format return \strtolower((string) \preg_replace('/[^a-z0-9]/i', '', $name)); } + /** + * The schemes an SDK example configures before calling a method: the first + * `authCount` accepted schemes offered on the platform, plus the path-bound + * schemes of a location method. Flat for a platform document; keyed by + * platform for the canonical document. + * + * @param array> $securities + * @param list $locationKeys + * @param list $platforms + * @return array + */ + private function getExampleAuth(array $securities, array $locationKeys, array $platforms): array + { + $auth = []; + + foreach ($this->platform === null ? $platforms : [$this->platform] as $platform) { + $offered = \array_intersect_key($securities, $this->keys[$platform] ?? []); + $slice = \array_slice($offered, 0, $this->authCounts[$platform] ?? 0); + + foreach ($locationKeys as $key) { + if (isset($this->keys[$platform][$key])) { + $slice[$key] = []; + } + } + + $auth[$platform] = $slice; + } + + return $this->platform === null ? $auth : ($auth[$this->platform] ?? []); + } + public function parse(): array { + $schemes = $this->getSecuritySchemes(); /** * Specifications (v3.0.0): * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md @@ -207,7 +239,7 @@ class OpenAPI3 extends Format 'tags' => $this->services, 'components' => [ 'schemas' => [], - 'securitySchemes' => $this->keys, + 'securitySchemes' => $schemes, ], 'externalDocs' => [ 'description' => $this->getParam('docs.description'), @@ -249,7 +281,7 @@ class OpenAPI3 extends Format $sdkPlatforms = \array_merge($sdkPlatforms, $method->getPlatforms()); } $sdkPlatforms = \array_values(\array_unique($sdkPlatforms)); - if (!\in_array($this->platform, $sdkPlatforms, true)) { + if ($this->platform === null ? $sdkPlatforms === [] : !\in_array($this->platform, $sdkPlatforms, true)) { continue; } @@ -308,13 +340,13 @@ class OpenAPI3 extends Format $methodSdkPlatforms = $methodObj->getPlatforms(); - if (!\in_array($this->platform, $methodSdkPlatforms, true)) { + if ($this->platform === null ? $methodSdkPlatforms === [] : !\in_array($this->platform, $methodSdkPlatforms, true)) { continue; } $methodSecurities = [($methodObj->getLocationAuth()[0] ?? 'Project') => []]; foreach ($methodObj->getAuth() as $security) { - if (\array_key_exists($security->value, $this->keys)) { + if (\array_key_exists($security->value, $schemes)) { $methodSecurities[$security->value] = []; } } @@ -324,7 +356,7 @@ class OpenAPI3 extends Format 'namespace' => $methodObj->getNamespace(), 'platforms' => $methodSdkPlatforms, 'desc' => $methodObj->getDesc(), - 'auth' => \array_slice($methodSecurities, 0, $this->authCount), + 'auth' => $this->getExampleAuth($methodSecurities, [], $methodSdkPlatforms), 'parameters' => [], 'required' => [], 'responses' => [], @@ -532,20 +564,18 @@ class OpenAPI3 extends Format foreach ($sdk->getAuth() as $security) { /** @var AuthType $security */ - if (array_key_exists($security->value, $this->keys)) { + if (\array_key_exists($security->value, $schemes)) { $securities[$security->value] = []; } } - $temp['x-appwrite']['auth'] = array_slice($securities, 0, $this->authCount); + $locationKeys = $sdk->getType() === MethodType::LOCATION + ? \array_values(\array_filter($sdk->getLocationAuth(), fn (string $key) => \array_key_exists($key, $schemes))) + : []; + $temp['x-appwrite']['auth'] = $this->getExampleAuth($securities, $locationKeys, $sdkPlatforms); - if ($sdk->getType() === MethodType::LOCATION) { - foreach ($sdk->getLocationAuth() as $key) { - if (\array_key_exists($key, $this->keys)) { - $securities[$key] = []; - $temp['x-appwrite']['auth'][$key] = []; - } - } + foreach ($locationKeys as $key) { + $securities[$key] = []; } $temp['security'][] = $securities; diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index d64ca24c40..a7e0ebeb08 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -124,7 +124,7 @@ final class FormatTest extends TestCase { parent::setUp(); - $this->format = new TestFormat(new Container(), [], [], [], [], 0, 'console'); + $this->format = new TestFormat(new Container(), [], [], [], [], ['console' => 0], 'console'); } public function testProjectRequestParameterOverrides(): void @@ -182,7 +182,7 @@ final class FormatTest extends TestCase new ArrayList(new Text(255), 10), ]), 'Metric names.', false, enum: new Enum(name: 'TestMetric')); - $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $this->assertSame([ 'type' => 'string', @@ -220,7 +220,7 @@ final class FormatTest extends TestCase map: ['basic' => 'Basic', 'advanced' => 'Advanced'], )); - $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $kind = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']['kind']; $this->assertSame('TestKind', $kind['title']); @@ -256,7 +256,7 @@ final class FormatTest extends TestCase [$route], [], [], - 0, + ['console' => 0], 'console', ); @@ -282,7 +282,7 @@ final class FormatTest extends TestCase responses: [new SDKResponse(code: Response::STATUS_CODE_OK, model: Response::MODEL_HEALTH_STATUS)], )); - $spec = (new OpenAPI3(new Container(), [], [$route], [new HealthStatus()], [], 0, 'console'))->parse(); + $spec = (new OpenAPI3(new Container(), [], [$route], [new HealthStatus()], [], ['console' => 0], 'console'))->parse(); $status = $spec['components']['schemas']['healthStatus']['properties']['status']; $this->assertSame('HealthCheckStatus', $status['title']); @@ -312,7 +312,7 @@ final class FormatTest extends TestCase )) ->param('userId', '', new CustomId(), 'User ID.'); - $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $userId = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']['userId']; @@ -344,7 +344,7 @@ final class FormatTest extends TestCase ->param('enabled', false, new BooleanValidator(true), 'Enabled.', example: 'true') ->param('text', '', new Text(64), 'Text.', example: '["one","two"]'); - $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']; $this->assertEquals((object) ['enabled' => true], $properties['metadata']['example']); @@ -376,7 +376,7 @@ final class FormatTest extends TestCase ->param('labels', [], new ArrayList(new Text(16)), 'Labels.', optional: true) ->param('values', [], new ArrayList(new MixedValidator()), 'Values.', optional: true); - $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']; $this->assertSame(['type' => 'number', 'format' => 'double'], $properties['percents']['items']); @@ -408,7 +408,7 @@ final class FormatTest extends TestCase ->param('name', '', new Text(128), 'Original description.') ->param('engine', 'mysql', new Text(16), 'Engine.', true); - $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']; @@ -440,7 +440,7 @@ final class FormatTest extends TestCase ->param('name', 'default-name', new Text(128), 'Original description.', true) ->param('engine', 'mysql', new Text(16), 'Engine.', true); - $format = new class (new Container(), [], [], [], [], 0, 'console') extends OpenAPI3 { + $format = new class (new Container(), [], [], [], [], ['console' => 0], 'console') extends OpenAPI3 { /** * @return array> */ @@ -477,7 +477,7 @@ final class FormatTest extends TestCase ->param('testId', '', new Text(256), 'Test ID.') ->param('transactionId', null, new Nullable(new Text(256)), 'Transaction ID.', true); - $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $this->assertArrayNotHasKey('requestBody', $openApi['paths']['/tests/{testId}']['delete']); $this->assertCount(2, $openApi['paths']['/tests/{testId}']['delete']['parameters']); @@ -510,7 +510,7 @@ final class FormatTest extends TestCase ->param('testId', '', new Text(256), 'Test ID.') ->param('name', null, new Nullable(new Text(256)), 'Test name.', true); - $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $get = $openApi['paths']['/tests/{testId}']['get']; $post = $openApi['paths']['/tests/{testId}']['post']; @@ -552,7 +552,7 @@ final class FormatTest extends TestCase new ErrorModel(), ]; - $openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], ['console' => 0], 'console'))->parse(); $openApiPrefs = $openApi['components']['schemas']['team']['properties']['prefs']; @@ -624,7 +624,7 @@ final class FormatTest extends TestCase ], )); - $openApi = (new OpenAPI3(new Container(), [], [$route], [$parent, $child], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [$parent, $child], [], ['console' => 0], 'console'))->parse(); $property = $openApi['components']['schemas']['parentWithoutExample']['properties']['child']; $this->assertSame('object', $property['type']); @@ -652,7 +652,7 @@ final class FormatTest extends TestCase ], )); - $openApi = (new OpenAPI3(new Container(), [], [$route], [new ErrorDev()], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [new ErrorDev()], [], ['console' => 0], 'console'))->parse(); $trace = $openApi['components']['schemas']['errorDev']['properties']['trace']; $this->assertSame('array', $trace['type']); @@ -679,7 +679,7 @@ final class FormatTest extends TestCase ->param('sessionId', 'current', new Text(256), 'Session ID.', true) ->param('filter', '', new Text(256), 'Optional query filter.', true); - $openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], ['console' => 0], 'console'))->parse(); $parameters = []; foreach ($openApi['paths']['/tests/{sessionId}']['get']['parameters'] as $parameter) { @@ -727,7 +727,7 @@ final class FormatTest extends TestCase new ErrorModel(), ]; - $openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], ['console' => 0], 'console'))->parse(); $properties = $openApi['components']['schemas']['usageProject']['properties']; @@ -765,7 +765,7 @@ final class FormatTest extends TestCase ], )); - $openApi = (new OpenAPI3(new Container(), [], [$route], [new Migration()], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [new Migration()], [], ['console' => 0], 'console'))->parse(); $resourceData = $openApi['components']['schemas']['migration']['properties']['resourceData']; $this->assertSame('array', $resourceData['type']); @@ -844,7 +844,7 @@ final class FormatTest extends TestCase new AlgoMd5(), ]; - $openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], $models, [], ['console' => 0], 'console'))->parse(); $openApiHashOptions = $openApi['components']['schemas']['user']['properties']['hashOptions']; @@ -890,7 +890,7 @@ final class FormatTest extends TestCase ], )); - $openApi = (new OpenAPI3(new Container(), [], [$requestRoute, $modelRoute], [new AttributeLine()], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$requestRoute, $modelRoute], [new AttributeLine()], [], ['console' => 0], 'console'))->parse(); $openApiRequestDefault = $openApi['paths']['/tests/spatial']['post']['requestBody']['content']['application/json']['schema']['properties']['default']; $openApiModelDefault = $openApi['components']['schemas']['attributeLine']['properties']['default']; @@ -929,7 +929,7 @@ final class FormatTest extends TestCase ->param('nullablePassword', null, new Nullable(new PasswordFormat(new Text(256, 0))), 'Nullable password.', true) ->param('name', '', new Text(256), 'Name.'); - $openApi = (new OpenAPI3(new Container(), [], [$route], [new Webhook()], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [new Webhook()], [], ['console' => 0], 'console'))->parse(); $openApiProperties = $openApi['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']; @@ -970,7 +970,7 @@ final class FormatTest extends TestCase )) ->param('testId', '', new Text(256), 'Test ID.'); - $openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], ['console' => 0], 'console'))->parse(); $openApiMethod = $openApi['paths']['/tests/{testId}']['delete']; @@ -1007,7 +1007,7 @@ final class FormatTest extends TestCase contentType: $contentType, )); - $openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [new NoneModel()], [], ['console' => 0], 'console'))->parse(); $openApiMethod = $openApi['paths']['/tests/file']['get']; @@ -1042,7 +1042,7 @@ final class FormatTest extends TestCase ], )); - $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $openApiQuery = $openApi['paths']['/tests/graphql']['post']['requestBody']['content']['application/json']['schema']['properties']['query']; @@ -1104,7 +1104,7 @@ final class FormatTest extends TestCase )); } - $openApi = (new OpenAPI3(new Container(), [], $routes, $models, [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], $routes, $models, [], ['console' => 0], 'console'))->parse(); $openApiOptions = $openApi['components']['schemas']['provider']['properties']['options']; @@ -1147,7 +1147,7 @@ final class FormatTest extends TestCase ->param('repositoryQueries', [], new VcsRepositories(), 'Repository queries.', true) ->param('deepQueries', [], $deepSubclass, 'Deeply nested queries.', true); - $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $openApi = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $parameters = $openApi['paths']['/tests/queries']['get']['parameters']; $schemas = \array_column($parameters, 'schema', 'name'); @@ -1178,7 +1178,7 @@ final class FormatTest extends TestCase ->param('min', 0, new Range(0, 100), 'Minimum.', example: '0') ->param('label', '', new Text(64), 'Label.', example: '0'); - $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']; // "0" is falsy, so a truthiness check silently discards it and falls back @@ -1208,7 +1208,7 @@ final class FormatTest extends TestCase ->param('domain', '', new Domain(), 'Domain name.') ->param('background', '', new HexColor(), 'Background colour.'); - $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse(); $properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']; // Without a case of their own these validators fell through to the @@ -1242,7 +1242,7 @@ final class FormatTest extends TestCase ], ); - $methods = $this->sdkMethods((new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse()); + $methods = $this->sdkMethods((new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse()); $this->assertContains('transactionId', $methods['createDocument']); $this->assertContains('transactionId', $methods['createDocuments']); @@ -1268,7 +1268,7 @@ final class FormatTest extends TestCase ], ); - $methods = $this->sdkMethods((new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse()); + $methods = $this->sdkMethods((new OpenAPI3(new Container(), [], [$route], [], [], ['console' => 0], 'console'))->parse()); $this->assertNotContains('transactionId', $methods['createDocument']); $this->assertNotContains('transactionId', $methods['createDocuments']); @@ -1278,6 +1278,114 @@ final class FormatTest extends TestCase * @param list $createDocument * @param list $createDocuments */ + public function testCanonicalDocumentKeysExampleAuthByPlatform(): void + { + Method::$processed = []; + Method::$errors = []; + + $route = (new Route('GET', '/v1/account')) + ->desc('Get account') + ->label('scope', 'account') + ->label('sdk', new Method( + namespace: 'account', + group: null, + name: 'get', + description: 'Get account.', + auth: [AuthType::SESSION, AuthType::KEY, AuthType::ADMIN], + responses: [], + )); + + $keys = $this->platformKeys(); + $authCounts = ['client' => 1, 'server' => 2, 'console' => 1]; + + $canonical = (new OpenAPI3(new Container(), [], [$route], [], $keys, $authCounts, null))->parse(); + $server = (new OpenAPI3(new Container(), [], [$route], [], $keys, $authCounts, 'server'))->parse(); + + $operation = $canonical['paths']['/account']['get']; + $this->assertSame(['client', 'server', 'console'], $operation['x-appwrite']['platforms']); + $this->assertSame([ + 'client' => ['Project' => []], + 'server' => ['Project' => [], 'Session' => []], + 'console' => ['Project' => []], + ], $operation['x-appwrite']['auth']); + $this->assertSame(['Project' => [], 'Session' => [], 'Key' => []], $operation['security'][0]); + + $this->assertSame(['Project' => [], 'Session' => []], $server['paths']['/account']['get']['x-appwrite']['auth']); + $this->assertSame(['Project' => [], 'Session' => [], 'Key' => []], $server['paths']['/account']['get']['security'][0]); + + $this->assertSame(['Project', 'Session', 'Key'], \array_keys($canonical['components']['securitySchemes'])); + $this->assertSame(['client', 'server', 'console'], $canonical['components']['securitySchemes']['Project']['x-appwrite']['platforms']); + $this->assertSame(['server'], $canonical['components']['securitySchemes']['Key']['x-appwrite']['platforms']); + $this->assertSame(['Project', 'Key', 'Session'], \array_keys($server['components']['securitySchemes'])); + $this->assertSame(['server'], $server['components']['securitySchemes']['Key']['x-appwrite']['platforms']); + } + + public function testCanonicalDocumentListsEveryAliasVariant(): void + { + Method::$processed = []; + Method::$errors = []; + + $route = (new Route('PATCH', '/v1/presences/:presenceId')) + ->desc('Update presence') + ->label('scope', 'presence') + ->label('sdk', [ + new Method( + namespace: 'presences', + group: null, + name: 'update', + description: 'Update presence.', + auth: [AuthType::SESSION], + responses: [], + parameters: [new Parameter('presenceId', optional: false)], + ), + new Method( + namespace: 'presences', + group: null, + name: 'update', + description: 'Update presence for a user.', + auth: [AuthType::KEY], + responses: [], + parameters: [new Parameter('presenceId', optional: false), new Parameter('userId', optional: false)], + ), + ]) + ->param('presenceId', '', new Text(256), 'Presence ID.') + ->param('userId', '', new Text(256), 'User ID.', true); + + $keys = $this->platformKeys(); + $authCounts = ['client' => 1, 'server' => 2, 'console' => 1]; + + $canonical = (new OpenAPI3(new Container(), [], [$route], [], $keys, $authCounts, null))->parse()['paths']['/presences/{presenceId}']['patch']; + $client = (new OpenAPI3(new Container(), [], [$route], [], $keys, $authCounts, 'client'))->parse()['paths']['/presences/{presenceId}']['patch']; + + $this->assertSame(['client', 'server'], $canonical['x-appwrite']['platforms']); + $this->assertCount(2, $canonical['x-appwrite']['methods']); + $this->assertSame(['client'], $canonical['x-appwrite']['methods'][0]['platforms']); + $this->assertSame(['client' => ['Project' => []]], $canonical['x-appwrite']['methods'][0]['auth']); + $this->assertSame(['presenceId'], $canonical['x-appwrite']['methods'][0]['required']); + $this->assertSame(['server'], $canonical['x-appwrite']['methods'][1]['platforms']); + $this->assertSame(['server' => ['Project' => [], 'Key' => []]], $canonical['x-appwrite']['methods'][1]['auth']); + $this->assertSame(['presenceId', 'userId'], $canonical['x-appwrite']['methods'][1]['required']); + + $this->assertCount(1, $client['x-appwrite']['methods']); + $this->assertSame(['Project' => []], $client['x-appwrite']['methods'][0]['auth']); + } + + /** + * @return array>> + */ + private function platformKeys(): array + { + $project = ['type' => 'apiKey', 'name' => 'X-Appwrite-Project', 'in' => 'header']; + $session = ['type' => 'apiKey', 'name' => 'X-Appwrite-Session', 'in' => 'header']; + $key = ['type' => 'apiKey', 'name' => 'X-Appwrite-Key', 'in' => 'header']; + + return [ + 'client' => ['Project' => $project, 'Session' => $session], + 'server' => ['Project' => $project, 'Key' => $key, 'Session' => $session], + 'console' => ['Project' => $project], + ]; + } + private function createDocumentsRoute(array $createDocument, array $createDocuments): Route { return (new Route('POST', '/v1/documentsdb/:databaseId/collections/:collectionId/documents')) From 71e89686bc221f41aad342cf755c4fbc8427de75 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Mon, 7 Sep 2026 11:13:57 +0100 Subject: [PATCH 2/3] test: keep the createDocumentsRoute docblock on its method --- tests/unit/SDK/Specification/FormatTest.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index a7e0ebeb08..b46fb5de87 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -1274,10 +1274,6 @@ final class FormatTest extends TestCase $this->assertNotContains('transactionId', $methods['createDocuments']); } - /** - * @param list $createDocument - * @param list $createDocuments - */ public function testCanonicalDocumentKeysExampleAuthByPlatform(): void { Method::$processed = []; @@ -1386,6 +1382,10 @@ final class FormatTest extends TestCase ]; } + /** + * @param list $createDocument + * @param list $createDocuments + */ private function createDocumentsRoute(array $createDocument, array $createDocuments): Route { return (new Route('POST', '/v1/documentsdb/:databaseId/collections/:collectionId/documents')) From eeeb78d901d23bc6e39a6b35ec62dc5c4420d709 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Mon, 7 Sep 2026 11:21:18 +0100 Subject: [PATCH 3/3] chore: update sdk-generator to 4.9.0 4.9.0 reads x-appwrite.auth keyed by platform, which the canonical document emits. --- composer.lock | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/composer.lock b/composer.lock index d438b61769..dd24ea6ef0 100644 --- a/composer.lock +++ b/composer.lock @@ -5465,16 +5465,16 @@ "packages-dev": [ { "name": "appwrite/sdk-generator", - "version": "4.7.8", + "version": "4.9.0", "source": { "type": "git", "url": "https://github.com/appwrite/sdk-generator.git", - "reference": "0f1b33dc784d8a2243555464e3543c01c0f2393b" + "reference": "888b0ecdc0f755787302b24d3f41b5875f6ef99b" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/appwrite/sdk-generator/zipball/0f1b33dc784d8a2243555464e3543c01c0f2393b", - "reference": "0f1b33dc784d8a2243555464e3543c01c0f2393b", + "url": "https://api.github.com/repos/appwrite/sdk-generator/zipball/888b0ecdc0f755787302b24d3f41b5875f6ef99b", + "reference": "888b0ecdc0f755787302b24d3f41b5875f6ef99b", "shasum": "" }, "require": { @@ -5484,7 +5484,7 @@ "matthiasmullie/minify": "^1.3", "php": ">=8.5", "twig/twig": "^3.28", - "utopia-php/openapi": "^0.2.0" + "utopia-php/openapi": "^0.2.1" }, "require-dev": { "brianium/paratest": "^7", @@ -5511,9 +5511,9 @@ "description": "SDK generator for Appwrite APIs across multiple programming languages and platforms", "support": { "issues": "https://github.com/appwrite/sdk-generator/issues", - "source": "https://github.com/appwrite/sdk-generator/tree/4.7.8" + "source": "https://github.com/appwrite/sdk-generator/tree/4.9.0" }, - "time": "2026-09-05T14:37:38+00:00" + "time": "2026-09-07T10:19:46+00:00" }, { "name": "brianium/paratest",