From d1502bc7d64bd6cafd6fc5350c0f3cdb944a34df Mon Sep 17 00:00:00 2001
From: Chirag Aggarwal <chiragaggarwal5k@gmail.com>
Date: Thu, 6 Feb 2025 11:08:58 +0000
Subject: [PATCH] chore: update descriptions for token endpoints

---
 .../Storage/Http/Tokens/Buckets/Files/Create.php       |  4 +++-
 .../Storage/Http/Tokens/Buckets/Files/XList.php        |  4 +++-
 .../Platform/Modules/Storage/Http/Tokens/Delete.php    |  4 +++-
 .../Platform/Modules/Storage/Http/Tokens/Get.php       |  4 +++-
 .../Platform/Modules/Storage/Http/Tokens/JWT/Get.php   |  4 +++-
 .../Platform/Modules/Storage/Http/Tokens/Update.php    |  4 +++-
 src/Appwrite/SDK/Method.php                            | 10 ++++++----
 src/Appwrite/Specification/Format/OpenAPI3.php         |  5 ++++-
 src/Appwrite/Specification/Format/Swagger2.php         |  5 ++++-
 9 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Buckets/Files/Create.php b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Buckets/Files/Create.php
index 847a1d32b1..bf2b198890 100644
--- a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Buckets/Files/Create.php
+++ b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Buckets/Files/Create.php
@@ -47,7 +47,9 @@ class Create extends Action
         ->label('sdk', new Method(
             namespace: 'tokens',
             name: 'createFileToken',
-            description: '',
+            description: <<<EOT
+            Create a new token. A token is linked to a file or a bucket and manages permissions for those file(s). Token can be passed as a header or request get parameter.
+            EOT,
             auth: [AuthType::SESSION, AuthType::KEY, AuthType::JWT],
             responses: [
                 new SDKResponse(
diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Buckets/Files/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Buckets/Files/XList.php
index 214e349a72..c7746702fa 100644
--- a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Buckets/Files/XList.php
+++ b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Buckets/Files/XList.php
@@ -37,7 +37,9 @@ class XList extends Action
             ->label('sdk', new Method(
                 namespace: 'tokens',
                 name: 'list',
-                description: '',
+                description: <<<EOT
+                List all the tokens created for a specific file or bucket. You can use the query params to filter your results.
+                EOT,
                 auth: [AuthType::SESSION, AuthType::KEY, AuthType::JWT],
                 responses: [
                     new SDKResponse(
diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Delete.php b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Delete.php
index dfad05e2d4..fe5387b862 100644
--- a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Delete.php
+++ b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Delete.php
@@ -41,7 +41,9 @@ class Delete extends Action
         ->label('sdk', new Method(
             namespace: 'tokens',
             name: 'delete',
-            description: '',
+            description: <<<EOT
+            Delete a token by its unique ID.
+            EOT,
             auth: [AuthType::SESSION, AuthType::KEY, AuthType::JWT],
             responses: [
                 new SDKResponse(
diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Get.php b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Get.php
index 2f15a52f4a..2d585e222b 100644
--- a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Get.php
+++ b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Get.php
@@ -34,7 +34,9 @@ class Get extends Action
         ->label('sdk', new Method(
             namespace: 'tokens',
             name: 'get',
-            description: '',
+            description: <<<EOT
+            Get a token by its unique ID.
+            EOT,
             auth: [AuthType::SESSION, AuthType::KEY, AuthType::JWT],
             responses: [
                 new SDKResponse(
diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/JWT/Get.php b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/JWT/Get.php
index 986700cb0d..ce9c26e8e6 100644
--- a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/JWT/Get.php
+++ b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/JWT/Get.php
@@ -37,7 +37,9 @@ class Get extends Action
         ->label('sdk', new Method(
             namespace: 'tokens',
             name: 'getJWT',
-            description: '',
+            description: <<<EOT
+            Get a JWT based token by its unique ID. You can use the JWT to authenticate on behalf of the user.
+            EOT,
             auth: [AuthType::SESSION, AuthType::KEY, AuthType::JWT],
             responses: [
                 new SDKResponse(
diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Update.php b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Update.php
index 39e6e306ae..81e53f6c9e 100644
--- a/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Update.php
+++ b/src/Appwrite/Platform/Modules/Storage/Http/Tokens/Update.php
@@ -48,7 +48,9 @@ class Update extends Action
         ->label('sdk', new Method(
             namespace: 'tokens',
             name: 'update',
-            description: '',
+            description: <<<EOT
+            Update a token by its unique ID. Use this endpoint to update a token's expiry date or permissions.
+            EOT,
             auth: [AuthType::SESSION, AuthType::KEY, AuthType::JWT],
             responses: [
                 new SDKResponse(
diff --git a/src/Appwrite/SDK/Method.php b/src/Appwrite/SDK/Method.php
index 626459ea7f..8d85f158cb 100644
--- a/src/Appwrite/SDK/Method.php
+++ b/src/Appwrite/SDK/Method.php
@@ -87,11 +87,13 @@ class Method
             return;
         }
 
-        $descPath = $this->getDescriptionFilePath();
+        if (\str_ends_with($desc, '.md')) {
+            $descPath = $this->getDescriptionFilePath();
 
-        if (empty($descPath)) {
-            self::$errors[] = "Error with {$this->getRouteName()} method: Description file not found at {$desc}";
-            return;
+            if (empty($descPath)) {
+                self::$errors[] = "Error with {$this->getRouteName()} method: Description file not found at {$desc}";
+                return;
+            }
         }
     }
 
diff --git a/src/Appwrite/Specification/Format/OpenAPI3.php b/src/Appwrite/Specification/Format/OpenAPI3.php
index bd5405539d..e60d342b0b 100644
--- a/src/Appwrite/Specification/Format/OpenAPI3.php
+++ b/src/Appwrite/Specification/Format/OpenAPI3.php
@@ -177,11 +177,14 @@ class OpenAPI3 extends Format
 
             $namespace = $sdk->getNamespace() ?? 'default';
 
+            $desc = $desc ?? '';
+            $descContents = \str_ends_with($desc, '.md') ? \file_get_contents($desc) : $desc;
+
             $temp = [
                 'summary' => $route->getDesc(),
                 'operationId' => $namespace . ucfirst($method),
                 'tags' => [$namespace],
-                'description' => ($desc) ? \file_get_contents($desc) : '',
+                'description' => $descContents,
                 'responses' => [],
                 'x-appwrite' => [ // Appwrite related metadata
                     'method' => $method,
diff --git a/src/Appwrite/Specification/Format/Swagger2.php b/src/Appwrite/Specification/Format/Swagger2.php
index 7277e3ab2b..fae164f0a6 100644
--- a/src/Appwrite/Specification/Format/Swagger2.php
+++ b/src/Appwrite/Specification/Format/Swagger2.php
@@ -173,13 +173,16 @@ class Swagger2 extends Format
 
             $namespace = $sdk->getNamespace() ?? 'default';
 
+            $desc = $desc ?? '';
+            $descContents = \str_ends_with($desc, '.md') ? \file_get_contents($desc) : $desc;
+
             $temp = [
                 'summary' => $route->getDesc(),
                 'operationId' => $namespace . ucfirst($method),
                 'consumes' => [],
                 'produces' => [],
                 'tags' => [$namespace],
-                'description' => ($desc) ? \file_get_contents($desc) : '',
+                'description' => $descContents,
                 'responses' => [],
                 'x-appwrite' => [ // Appwrite related metadata
                     'method' => $method,