From 0ffc90bd077c92f03e417d737f2c77c99ef682df Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Thu, 17 Sep 2026 15:50:44 +0100 Subject: [PATCH] refactor(specs): name the alias summary "summary" An operation carries its short title in the standard `summary` field and its prose in `description`. A method alias in `x-appwrite.methods[]` mirrors an operation, but carried the same short title under `desc` while keeping `description` as a separate sibling, so `desc` read like an abbreviation of the field sitting next to it. Emit `summary` instead, and rename the PHP side to match: Method::$desc becomes $summary with getSummary(), and the 16 call sites pass `summary:`. Route::getDesc() is Utopia's and is untouched. No consumer changes. The generator never read the key, deriving an alias summary from its name. Vibes already reads `additionalMethod.summary || additionalMethod.desc`, so it takes the new field on the first branch and its fallback can be dropped once historical specs stop mattering. While here, validateDesc() validates a description, so it is renamed to validateDescription() to keep it distinct from the new summary. --- .../Collections/Documents/Create.php | 4 ++-- .../Collections/Documents/Create.php | 4 ++-- .../Databases/Http/Embeddings/Text/Create.php | 2 +- .../Http/TablesDB/Tables/Rows/Create.php | 4 ++-- .../Collections/Documents/Create.php | 4 ++-- .../Modules/Presences/HTTP/Delete.php | 2 +- .../Platform/Modules/Presences/HTTP/Get.php | 2 +- .../Modules/Presences/HTTP/Update.php | 4 ++-- .../Modules/Presences/HTTP/Upsert.php | 4 ++-- .../Platform/Modules/Presences/HTTP/XList.php | 2 +- src/Appwrite/SDK/Method.php | 23 +++++++++---------- .../SDK/Specification/Format/OpenAPI3.php | 2 +- tests/unit/SDK/Specification/FormatTest.php | 3 +++ 13 files changed, 31 insertions(+), 29 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Databases/Http/Databases/Collections/Documents/Create.php b/src/Appwrite/Platform/Modules/Databases/Http/Databases/Collections/Documents/Create.php index e451447835..0b79dc90bd 100644 --- a/src/Appwrite/Platform/Modules/Databases/Http/Databases/Collections/Documents/Create.php +++ b/src/Appwrite/Platform/Modules/Databases/Http/Databases/Collections/Documents/Create.php @@ -77,7 +77,7 @@ class Create extends Action namespace: $this->getSDKNamespace(), group: $this->getSDKGroup(), name: self::getName(), - desc: 'Create document', + summary: 'Create document', description: '/docs/references/databases/create-document.md', auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], responses: [ @@ -104,7 +104,7 @@ class Create extends Action namespace: $this->getSDKNamespace(), group: $this->getSDKGroup(), name: $this->getBulkActionName(self::getName()), - desc: 'Create documents', + summary: 'Create documents', description: '/docs/references/databases/create-documents.md', auth: [AuthType::ADMIN, AuthType::KEY], responses: [ diff --git a/src/Appwrite/Platform/Modules/Databases/Http/DocumentsDB/Collections/Documents/Create.php b/src/Appwrite/Platform/Modules/Databases/Http/DocumentsDB/Collections/Documents/Create.php index ea7c96c1b4..1f48c594a0 100644 --- a/src/Appwrite/Platform/Modules/Databases/Http/DocumentsDB/Collections/Documents/Create.php +++ b/src/Appwrite/Platform/Modules/Databases/Http/DocumentsDB/Collections/Documents/Create.php @@ -60,7 +60,7 @@ class Create extends DocumentCreate namespace: 'documentsDB', group: $this->getSdkGroup(), name: 'createDocument', - desc: 'Create document', + summary: 'Create document', description: '/docs/references/documentsdb/create-document.md', auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], responses: [ @@ -83,7 +83,7 @@ class Create extends DocumentCreate namespace: 'documentsDB', group: $this->getSdkGroup(), name: 'createDocuments', - desc: 'Create documents', + summary: 'Create documents', description: '/docs/references/documentsdb/create-documents.md', auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], responses: [ diff --git a/src/Appwrite/Platform/Modules/Databases/Http/Embeddings/Text/Create.php b/src/Appwrite/Platform/Modules/Databases/Http/Embeddings/Text/Create.php index cdd6f79bda..763f47d9a2 100644 --- a/src/Appwrite/Platform/Modules/Databases/Http/Embeddings/Text/Create.php +++ b/src/Appwrite/Platform/Modules/Databases/Http/Embeddings/Text/Create.php @@ -57,7 +57,7 @@ class Create extends CreateDocumentAction namespace: 'embeddings', group: 'embeddings', name: 'createTextEmbeddings', - desc: 'Create Text Embedding', + summary: 'Create Text Embedding', description: '/docs/references/embeddings/create-text-embeddings.md', auth: [AuthType::ADMIN, AuthType::KEY, AuthType::JWT], responses: [ diff --git a/src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Tables/Rows/Create.php b/src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Tables/Rows/Create.php index d408783b5c..1f1179c34e 100644 --- a/src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Tables/Rows/Create.php +++ b/src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Tables/Rows/Create.php @@ -55,7 +55,7 @@ class Create extends DocumentCreate namespace: $this->getSDKNamespace(), group: $this->getSDKGroup(), name: self::getName(), - desc: 'Create row', + summary: 'Create row', description: '/docs/references/tablesdb/create-row.md', auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], responses: [ @@ -78,7 +78,7 @@ class Create extends DocumentCreate namespace: $this->getSDKNamespace(), group: $this->getSDKGroup(), name: $this->getBulkActionName(self::getName()), - desc: 'Create rows', + summary: 'Create rows', description: '/docs/references/tablesdb/create-rows.md', auth: [AuthType::ADMIN, AuthType::KEY], responses: [ diff --git a/src/Appwrite/Platform/Modules/Databases/Http/VectorsDB/Collections/Documents/Create.php b/src/Appwrite/Platform/Modules/Databases/Http/VectorsDB/Collections/Documents/Create.php index 680308544f..63600f9b8e 100644 --- a/src/Appwrite/Platform/Modules/Databases/Http/VectorsDB/Collections/Documents/Create.php +++ b/src/Appwrite/Platform/Modules/Databases/Http/VectorsDB/Collections/Documents/Create.php @@ -54,7 +54,7 @@ class Create extends DocumentCreate namespace: 'vectorsDB', group: $this->getSdkGroup(), name: 'createDocument', - desc: 'Create document', + summary: 'Create document', description: '/docs/references/vectorsdb/create-document.md', auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], responses: [ @@ -77,7 +77,7 @@ class Create extends DocumentCreate namespace: 'vectorsDB', group: $this->getSdkGroup(), name: 'createDocuments', - desc: 'Create documents', + summary: 'Create documents', description: '/docs/references/vectorsdb/create-documents.md', auth: [AuthType::ADMIN, AuthType::KEY], responses: [ diff --git a/src/Appwrite/Platform/Modules/Presences/HTTP/Delete.php b/src/Appwrite/Platform/Modules/Presences/HTTP/Delete.php index 66ab00c3a7..3938ae05d1 100644 --- a/src/Appwrite/Platform/Modules/Presences/HTTP/Delete.php +++ b/src/Appwrite/Platform/Modules/Presences/HTTP/Delete.php @@ -40,7 +40,7 @@ class Delete extends PlatformAction namespace: 'presences', group: 'presences', name: 'delete', - desc: 'Delete presence', + summary: 'Delete presence', description: '/docs/references/presences/delete.md', auth: [AuthType::ADMIN, AuthType::KEY, AuthType::SESSION, AuthType::JWT], responses: [ diff --git a/src/Appwrite/Platform/Modules/Presences/HTTP/Get.php b/src/Appwrite/Platform/Modules/Presences/HTTP/Get.php index ba6b769f70..06d3a49592 100644 --- a/src/Appwrite/Platform/Modules/Presences/HTTP/Get.php +++ b/src/Appwrite/Platform/Modules/Presences/HTTP/Get.php @@ -35,7 +35,7 @@ class Get extends PlatformAction namespace: 'presences', group: 'presences', name: 'get', - desc: 'Get presence', + summary: 'Get presence', description: '/docs/references/presences/get.md', auth: [AuthType::ADMIN, AuthType::KEY, AuthType::SESSION, AuthType::JWT], responses: [ diff --git a/src/Appwrite/Platform/Modules/Presences/HTTP/Update.php b/src/Appwrite/Platform/Modules/Presences/HTTP/Update.php index fc2f9c6036..d5d0466111 100644 --- a/src/Appwrite/Platform/Modules/Presences/HTTP/Update.php +++ b/src/Appwrite/Platform/Modules/Presences/HTTP/Update.php @@ -51,7 +51,7 @@ class Update extends PlatformAction namespace: 'presences', group: 'presences', name: 'update', - desc: 'Update presence', + summary: 'Update presence', description: '/docs/references/presences/update.md', auth: [AuthType::SESSION, AuthType::ADMIN], responses: [ @@ -74,7 +74,7 @@ class Update extends PlatformAction namespace: 'presences', group: 'presences', name: 'update', - desc: 'Update presence', + summary: 'Update presence', description: '/docs/references/presences/update.md', auth: [AuthType::KEY, AuthType::JWT], responses: [ diff --git a/src/Appwrite/Platform/Modules/Presences/HTTP/Upsert.php b/src/Appwrite/Platform/Modules/Presences/HTTP/Upsert.php index 245910d57c..49c304af02 100644 --- a/src/Appwrite/Platform/Modules/Presences/HTTP/Upsert.php +++ b/src/Appwrite/Platform/Modules/Presences/HTTP/Upsert.php @@ -52,7 +52,7 @@ class Upsert extends PlatformAction namespace: 'presences', group: 'presences', name: 'upsert', - desc: 'Upsert presence', + summary: 'Upsert presence', description: '/docs/references/presences/upsert.md', auth: [AuthType::SESSION, AuthType::ADMIN], responses: [ @@ -74,7 +74,7 @@ class Upsert extends PlatformAction namespace: 'presences', group: 'presences', name: 'upsert', - desc: 'Upsert presence', + summary: 'Upsert presence', description: '/docs/references/presences/upsert.md', auth: [AuthType::KEY, AuthType::JWT], responses: [ diff --git a/src/Appwrite/Platform/Modules/Presences/HTTP/XList.php b/src/Appwrite/Platform/Modules/Presences/HTTP/XList.php index 94dca8c4ee..656321199d 100644 --- a/src/Appwrite/Platform/Modules/Presences/HTTP/XList.php +++ b/src/Appwrite/Platform/Modules/Presences/HTTP/XList.php @@ -45,7 +45,7 @@ class XList extends PlatformAction namespace: 'presences', group: 'presences', name: 'list', - desc: 'List presences', + summary: 'List presences', description: '/docs/references/presences/list.md', auth: [AuthType::ADMIN, AuthType::KEY, AuthType::SESSION, AuthType::JWT], responses: [ diff --git a/src/Appwrite/SDK/Method.php b/src/Appwrite/SDK/Method.php index 3b62661a33..a36b9d5552 100644 --- a/src/Appwrite/SDK/Method.php +++ b/src/Appwrite/SDK/Method.php @@ -21,7 +21,6 @@ class Method * @param string $namespace * @param ?string $group * @param string $name - * @param string $desc * @param string $description * @param array $auth * @param array $responses @@ -33,7 +32,7 @@ class Method * @param ContentType $requestType * @param array $parameters * @param array $additionalParameters - * @param string $desc + * @param string $summary * @param bool $public Whether this method should be rendered on the website/documentation * @param array $locationAuth Security scheme keys for location-type methods: first is the required project binding; additional keys supplement the base auth as an optional alternative */ @@ -52,13 +51,13 @@ class Method protected ContentType $requestType = ContentType::JSON, protected array $parameters = [], protected array $additionalParameters = [], - protected string $desc = '', + protected string $summary = '', protected bool $public = true, protected array $locationAuth = [] ) { $this->validateMethod($name, $namespace); $this->validateAuthTypes($auth); - $this->validateDesc($description); + $this->validateDescription($description); foreach ($responses as $response) { $this->validateResponseModel($response->getModel()); @@ -89,18 +88,18 @@ class Method } } - protected function validateDesc(string $desc): void + protected function validateDescription(string $description): void { - if (empty($desc)) { + if (empty($description)) { self::$errors[] = "Error with {$this->getRouteName()} method: Description label is empty"; return; } - if (\str_ends_with($desc, '.md')) { - $descPath = $this->getDescriptionFilePath() ?: $this->getDescription(); + if (\str_ends_with($description, '.md')) { + $path = $this->getDescriptionFilePath() ?: $this->getDescription(); - if (empty($descPath)) { - self::$errors[] = "Error with {$this->getRouteName()} method: Description file not found at {$desc}"; + if (empty($path)) { + self::$errors[] = "Error with {$this->getRouteName()} method: Description file not found at {$description}"; return; } } @@ -147,9 +146,9 @@ class Method return $this->name; } - public function getDesc(): string + public function getSummary(): string { - return $this->desc; + return $this->summary; } public function getDescription(): string diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index cf5bb66056..2dac6fc3d4 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -356,7 +356,7 @@ class OpenAPI3 extends Format 'name' => $methodObj->getMethodName(), 'namespace' => $methodObj->getNamespace(), 'platforms' => $methodSdkPlatforms, - 'desc' => $methodObj->getDesc(), + 'summary' => $methodObj->getSummary(), 'auth' => $this->getExampleAuth($methodSecurities, [], $methodSdkPlatforms), 'parameters' => [], 'required' => [], diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index 47e6ed01f3..02c372b1e5 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -1525,6 +1525,7 @@ final class FormatTest extends TestCase auth: [AuthType::KEY], responses: [], parameters: [new Parameter('presenceId', optional: false), new Parameter('userId', optional: false)], + summary: 'Update presence for a user', ), ]) ->param('presenceId', '', new Text(256), 'Presence ID.') @@ -1544,6 +1545,8 @@ final class FormatTest extends TestCase $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->assertSame('', $canonical['x-appwrite']['methods'][0]['summary']); + $this->assertSame('Update presence for a user', $canonical['x-appwrite']['methods'][1]['summary']); $this->assertCount(1, $client['x-appwrite']['methods']); $this->assertSame(['Project' => []], $client['x-appwrite']['methods'][0]['auth']);