mirror of
https://github.com/appwrite/appwrite.git
synced 2026-11-18 20:36:03 +00:00
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.
This commit is contained in:
13 files changed
+31
-29
No files matched your search
+2
-2
@@ -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: [
|
||||
|
||||
+2
-2
@@ -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: [
|
||||
|
||||
@@ -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: [
|
||||
|
||||
@@ -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: [
|
||||
|
||||
+2
-2
@@ -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: [
|
||||
|
||||
@@ -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: [
|
||||
|
||||
@@ -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: [
|
||||
|
||||
@@ -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: [
|
||||
|
||||
@@ -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: [
|
||||
|
||||
@@ -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: [
|
||||
|
||||
+11
-12
@@ -21,7 +21,6 @@ class Method
|
||||
* @param string $namespace
|
||||
* @param ?string $group
|
||||
* @param string $name
|
||||
* @param string $desc
|
||||
* @param string $description
|
||||
* @param array<AuthType> $auth
|
||||
* @param array<SDKResponse> $responses
|
||||
@@ -33,7 +32,7 @@ class Method
|
||||
* @param ContentType $requestType
|
||||
* @param array<Parameter> $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<string> $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
|
||||
|
||||
@@ -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' => [],
|
||||
|
||||
@@ -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']);
|
||||
|
||||
Reference in new issue
Block a user