Merge pull request #9307 from appwrite/chore-http-descriptions

Chore: Deprecate markdown docs refferences
This commit is contained in:
Matej Bačo 2025-02-05 16:51:49 +01:00 committed by GitHub
commit e0131aa749
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
49 changed files with 7649 additions and 269 deletions

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

View file

@ -130,7 +130,7 @@ function router(App $utopia, Database $dbForPlatform, callable $getProjectDB, Sw
};
}
if ($type === 'function') {
if ($type === 'function' || $type === 'site') {
$method = $utopia->getRoute()?->getLabel('sdk', null);
if (empty($method)) {

View file

@ -1 +0,0 @@
Create a new build for an existing site deployment. This endpoint allows you to rebuild a deployment with the updated site configuration, including its install command, build command, and output directory if they have been modified. The build process will be queued and executed asynchronously. The original deployment's code will be preserved and used for the new build.

View file

@ -1 +0,0 @@
Create a new site environment variable. These variables can be accessed during build and runtime (server-side rendering) as environment variables.

View file

@ -1 +0,0 @@
Delete a code deployment by its unique ID.

View file

@ -1 +0,0 @@
Get a code deployment by its unique ID.

View file

@ -1 +0,0 @@
Get a list of all the site's code deployments. You can use the query params to filter your results.

View file

@ -1 +0,0 @@
Get a list of all variables of a specific site.

View file

@ -53,7 +53,13 @@ class Create extends Action
->label('sdk', new Method(
namespace: 'functions',
name: 'createDeployment',
description: '/docs/references/functions/create-deployment.md',
description: <<<EOT
Create a new function code deployment. Use this endpoint to upload a new version of your code function. To execute your newly uploaded code, you'll need to update the function's deployment to use your new deployment UID.
This endpoint accepts a tar.gz file compressed with your code. Make sure to include any dependencies your code has within the compressed file. You can learn more about code packaging in the [Appwrite Cloud Functions tutorial](https://appwrite.io/docs/functions).
Use the "command" param to set the entrypoint used to execute your code.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -62,7 +62,9 @@ class Create extends Base
->label('sdk', new Method(
namespace: 'functions',
name: 'create',
description: '/docs/references/functions/create.md',
description: <<<EOT
Create a new function. You can pass a list of [permissions](https://appwrite.io/docs/permissions) to allow different project users or team with access to execute the function using the client API.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -61,7 +61,9 @@ class Update extends Base
->label('sdk', new Method(
namespace: 'functions',
name: 'update',
description: '/docs/references/functions/update-function.md',
description: <<<EOT
Update function by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -39,7 +39,9 @@ class XList extends Base
->label('sdk', new Method(
namespace: 'functions',
name: 'list',
description: '/docs/references/functions/list-functions.md',
description: <<<EOT
Get a list of all the project's functions. You can use the query params to filter your results.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -34,7 +34,9 @@ class XList extends Base
->label('sdk', new Method(
namespace: 'functions',
name: 'listRuntimes',
description: '/docs/references/functions/list-runtimes.md',
description: <<<EOT
Get a list of all runtimes that are currently active on your instance.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -4,8 +4,8 @@ namespace Appwrite\Platform\Modules\Functions\Services;
use Appwrite\Platform\Modules\Functions\Http\Deployments\Create as CreateDeployment;
use Appwrite\Platform\Modules\Functions\Http\Functions\Create as CreateFunction;
use Appwrite\Platform\Modules\Functions\Http\Functions\XList as ListFunctions;
use Appwrite\Platform\Modules\Functions\Http\Functions\Update as UpdateFunction;
use Appwrite\Platform\Modules\Functions\Http\Functions\XList as ListFunctions;
use Appwrite\Platform\Modules\Functions\Http\Runtimes\XList as ListRuntimes;
use Utopia\Platform\Service;

View file

@ -39,7 +39,9 @@ class Create extends Action
->label('sdk', new Method(
namespace: 'sites',
name: 'createDeploymentBuild',
description: '/docs/references/sites/create-deployment-build.md',
description: <<<EOT
Create a new build for an existing site deployment. This endpoint allows you to rebuild a deployment with the updated site configuration, including its commands and output directory if they have been modified. The build process will be queued and executed asynchronously. The original deployment's code will be preserved and used for the new build.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -3,6 +3,11 @@
namespace Appwrite\Platform\Modules\Sites\Http\Deployments\Builds\Download;
use Appwrite\Extend\Exception;
use Appwrite\SDK\AuthType;
use Appwrite\SDK\ContentType;
use Appwrite\SDK\Method;
use Appwrite\SDK\MethodType;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\Utopia\Response;
use Utopia\Database\Database;
use Utopia\Database\Validator\UID;
@ -28,13 +33,22 @@ class Get extends Action
->desc('Download build')
->groups(['api', 'sites'])
->label('scope', 'sites.read')
->label('sdk.auth', [APP_AUTH_TYPE_KEY, APP_AUTH_TYPE_JWT])
->label('sdk.namespace', 'sites')
->label('sdk.method', 'getDeploymentBuildDownload')
->label('sdk.description', '/docs/references/sites/get-deployment-build-download.md')
->label('sdk.response.code', Response::STATUS_CODE_OK)
->label('sdk.response.type', '*/*')
->label('sdk.methodType', 'location')
->label('sdk', new Method(
namespace: 'sites',
name: 'getDeploymentBuildDownload',
description: <<<EOT
Get a site build content by its unique ID. The endpoint response return with a 'Content-Disposition: attachment' header that tells the browser to start downloading the file to user downloads directory.
EOT,
auth: [AuthType::KEY, AuthType::JWT],
responses: [
new SDKResponse(
code: Response::STATUS_CODE_OK,
model: Response::MODEL_NONE
)
],
type: MethodType::LOCATION,
contentType: ContentType::ANY,
))
->param('siteId', '', new UID(), 'Site ID.')
->param('deploymentId', '', new UID(), 'Deployment ID.')
->inject('response')

View file

@ -41,7 +41,9 @@ class Update extends Action
->label('sdk', new Method(
namespace: 'sites',
name: 'updateDeploymentBuild',
description: '/docs/references/sites/update-deployment-build.md',
description: <<<EOT
Cancel an ongoing site deployment build. If the build is already in progress, it will be stopped and marked as canceled. If the build hasn't started yet, it will be marked as canceled without executing. You cannot cancel builds that have already completed (status 'ready') or failed. The response includes the final build status and details.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -53,7 +53,9 @@ class Create extends Action
->label('sdk', new Method(
namespace: 'sites',
name: 'createDeployment',
description: '/docs/references/sites/create-deployment.md',
description: <<<EOT
Create a new site code deployment. Use this endpoint to upload a new version of your site code. To activate your newly uploaded code, you'll need to update the function's deployment to use your new deployment ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -40,7 +40,9 @@ class Delete extends Action
->label('sdk', new Method(
namespace: 'sites',
name: 'deleteDeployment',
description: '/docs/references/sites/delete-deployment.md',
description: <<<EOT
Delete a site deployment by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(
@ -61,7 +63,7 @@ class Delete extends Action
->callback([$this, 'action']);
}
public function action(string $siteId, string $deploymentId, Response $response, Database $dbForProject, Delete $queueForDeletes, Event $queueForEvents, Device $deviceForSites, Device $deviceForFunctions)
public function action(string $siteId, string $deploymentId, Response $response, Database $dbForProject, DeleteEvent $queueForDeletes, Event $queueForEvents, Device $deviceForSites, Device $deviceForFunctions)
{
$site = $dbForProject->getDocument('sites', $siteId);
if ($site->isEmpty()) {

View file

@ -3,6 +3,11 @@
namespace Appwrite\Platform\Modules\Sites\Http\Deployments\Download;
use Appwrite\Extend\Exception;
use Appwrite\SDK\AuthType;
use Appwrite\SDK\ContentType;
use Appwrite\SDK\Method;
use Appwrite\SDK\MethodType;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\Utopia\Response;
use Utopia\Database\Database;
use Utopia\Database\Validator\UID;
@ -28,13 +33,22 @@ class Get extends Action
->desc('Download deployment')
->groups(['api', 'sites'])
->label('scope', 'sites.read')
->label('sdk.auth', [APP_AUTH_TYPE_KEY, APP_AUTH_TYPE_JWT])
->label('sdk.namespace', 'sites')
->label('sdk.method', 'getDeploymentDownload')
->label('sdk.description', '/docs/references/sites/get-deployment-download.md')
->label('sdk.response.code', Response::STATUS_CODE_OK)
->label('sdk.response.type', '*/*')
->label('sdk.methodType', 'location')
->label('sdk', new Method(
namespace: 'sites',
name: 'getDeploymentDownload',
description: <<<EOT
Get a site deployment content by its unique ID. The endpoint response return with a 'Content-Disposition: attachment' header that tells the browser to start downloading the file to user downloads directory.
EOT,
auth: [AuthType::KEY, AuthType::JWT],
responses: [
new SDKResponse(
code: Response::STATUS_CODE_OK,
model: Response::MODEL_NONE
)
],
type: MethodType::LOCATION,
contentType: ContentType::ANY,
))
->param('siteId', '', new UID(), 'Site ID.')
->param('deploymentId', '', new UID(), 'Deployment ID.')
->inject('response')

View file

@ -35,7 +35,9 @@ class Get extends Action
->label('sdk', new Method(
namespace: 'sites',
name: 'getDeployment',
description: '/docs/references/sites/get-deployment.md',
description: <<<EOT
Get a site deployment by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -37,7 +37,9 @@ class Update extends Action
->label('sdk', new Method(
namespace: 'sites',
name: 'updateDeployment',
description: '/docs/references/sites/update-deployment.md',
description: <<<EOT
Update the site active deployment. Use this endpoint to switch the code deployment that should be used when visitor opens your site.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -39,7 +39,9 @@ class XList extends Action
->label('sdk', new Method(
namespace: 'sites',
name: 'listDeployments',
description: '/docs/references/sites/list-deployments.md',
description: <<<EOT
Get a list of all the site's code deployments. You can use the query params to filter your results.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -33,7 +33,9 @@ class XList extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'listFrameworks',
description: '/docs/references/sites/list-frameworks.md',
description: <<<EOT
Get a list of all frameworks that are currently available on the server instance.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -38,7 +38,9 @@ class Delete extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'deleteLog',
description: '/docs/references/sites/delete-log.md',
description: <<<EOT
Delete a site log by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -33,7 +33,9 @@ class Get extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'getLog',
description: '/docs/references/sites/get-log.md',
description: <<<EOT
Get a site request log by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -41,7 +41,9 @@ class XList extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'listLogs',
description: '/docs/references/sites/get-log.md',
description: <<<EOT
Get a list of all site logs. You can use the query params to filter your results.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -53,9 +53,11 @@ class Create extends Base
->label('audits.event', 'site.create')
->label('audits.resource', 'site/{response.$id}')
->label('sdk', new Method(
namespace: 'site',
namespace: 'sites',
name: 'create',
description: '/docs/references/sites/create.md',
description: <<<EOT
Create a new site.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -39,7 +39,9 @@ class Delete extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'delete',
description: '/docs/references/sites/delete.md',
description: <<<EOT
Delete a site by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -34,7 +34,9 @@ class Get extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'get',
description: '/docs/references/sites/get.md',
description: <<<EOT
Get a site by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -53,7 +53,9 @@ class Update extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'update',
description: '/docs/references/sites/update.md',
description: <<<EOT
Update site by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -38,7 +38,9 @@ class XList extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'list',
description: '/docs/references/sites/list.md',
description: <<<EOT
Get a list of all the project's sites. You can use the query params to filter your results.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -34,7 +34,9 @@ class Get extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'getTemplate',
description: '/docs/references/sites/get-template.md',
description: <<<EOT
Get a site template using ID. You can use template details in [createSite](/docs/references/cloud/server-nodejs/sites#create) method.
EOT,
auth: [AuthType::ADMIN],
responses: [
new SDKResponse(

View file

@ -35,7 +35,9 @@ class XList extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'listTemplates',
description: '/docs/references/sites/list-templates.md',
description: <<<EOT
List available site templates. You can use template details in [createSite](/docs/references/cloud/server-nodejs/sites#create) method.
EOT,
auth: [AuthType::ADMIN],
responses: [
new SDKResponse(

View file

@ -38,7 +38,9 @@ class Get extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'getUsage',
description: '/docs/references/sites/get-usage.md',
description: <<<EOT
Get usage metrics and statistics for a for a specific site. View statistics including total deployments, builds, executions, storage usage, and compute time. The response includes both current totals and historical data for each metric. Use the optional range parameter to specify the time window for historical data: 24h (last 24 hours), 30d (last 30 days), or 90d (last 90 days). If not specified, defaults to 30 days.
EOT,
auth: [AuthType::ADMIN],
responses: [
new SDKResponse(

View file

@ -36,7 +36,9 @@ class XList extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'listUsage',
description: '/docs/references/sites/list-usage.md',
description: <<<EOT
Get usage metrics and statistics for all sites in the project. View statistics including total deployments, builds, logs, storage usage, and compute time. The response includes both current totals and historical data for each metric. Use the optional range parameter to specify the time window for historical data: 24h (last 24 hours), 30d (last 30 days), or 90d (last 90 days). If not specified, defaults to 30 days.
EOT,
auth: [AuthType::ADMIN],
responses: [
new SDKResponse(

View file

@ -42,7 +42,9 @@ class Create extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'createVariable',
description: '/docs/references/sites/create-variable.md',
description: <<<EOT
Create a new site variable. These variables can be accessed during build and runtime (server-side rendering) as environment variables.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -36,7 +36,9 @@ class Delete extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'deleteVariable',
description: '/docs/references/sites/delete-variable.md',
description: <<<EOT
Delete a variable by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -35,7 +35,9 @@ class Get extends Base
new Method(
namespace: 'sites',
name: 'getVariable',
description: '/docs/references/sites/get-variable.md',
description: <<<EOT
Get a variable by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -37,7 +37,9 @@ class Update extends Base
->label('sdk', new Method(
namespace: 'sites',
name: 'updateVariable',
description: '/docs/references/sites/update-variable.md',
description: <<<EOT
Update variable by its unique ID.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -36,7 +36,9 @@ class XList extends Base
new Method(
namespace: 'sites',
name: 'listVariables',
description: '/docs/references/sites/list-variables.md',
description: <<<EOT
Get a list of all variables of a specific site.
EOT,
auth: [AuthType::KEY],
responses: [
new SDKResponse(

View file

@ -2,33 +2,33 @@
namespace Appwrite\Platform\Modules\Sites\Services;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Builds\Update as UpdateBuild;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Builds\Create as CreateBuild;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Builds\Download\Get as DownloadBuild;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Builds\Update as UpdateBuild;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Create as CreateDeployment;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Delete as DeleteDeployment;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Download\Get as DownloadDeployment;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Builds\Download\Get as DownloadBuild;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Get as GetDeployment;
use Appwrite\Platform\Modules\Sites\Http\Deployments\XList as ListDeployments;
use Appwrite\Platform\Modules\Sites\Http\Deployments\Update as UpdateDeployment;
use Appwrite\Platform\Modules\Sites\Http\Deployments\XList as ListDeployments;
use Appwrite\Platform\Modules\Sites\Http\Frameworks\XList as ListFrameworks;
use Appwrite\Platform\Modules\Sites\Http\Logs\Delete as DeleteLog;
use Appwrite\Platform\Modules\Sites\Http\Logs\Get as GetLog;
use Appwrite\Platform\Modules\Sites\Http\Logs\XList as ListLogs;
use Appwrite\Platform\Modules\Sites\Http\Sites\Create as CreateSite;
use Appwrite\Platform\Modules\Sites\Http\Sites\Delete as DeleteSite;
use Appwrite\Platform\Modules\Sites\Http\Sites\Get as GetSite;
use Appwrite\Platform\Modules\Sites\Http\Usage\Get as GetUsage;
use Appwrite\Platform\Modules\Sites\Http\Usage\XList as ListUsage;
use Appwrite\Platform\Modules\Sites\Http\Sites\XList as ListSites;
use Appwrite\Platform\Modules\Sites\Http\Sites\Update as UpdateSite;
use Appwrite\Platform\Modules\Sites\Http\Sites\XList as ListSites;
use Appwrite\Platform\Modules\Sites\Http\Templates\Get as GetTemplate;
use Appwrite\Platform\Modules\Sites\Http\Templates\XList as ListTemplates;
use Appwrite\Platform\Modules\Sites\Http\Frameworks\XList as ListFrameworks;
use Appwrite\Platform\Modules\Sites\Http\Usage\Get as GetUsage;
use Appwrite\Platform\Modules\Sites\Http\Usage\XList as ListUsage;
use Appwrite\Platform\Modules\Sites\Http\Variables\Create as CreateVariable;
use Appwrite\Platform\Modules\Sites\Http\Variables\Delete as DeleteVariable;
use Appwrite\Platform\Modules\Sites\Http\Variables\Get as GetVariable;
use Appwrite\Platform\Modules\Sites\Http\Variables\XList as ListVariables;
use Appwrite\Platform\Modules\Sites\Http\Variables\Update as UpdateVariable;
use Appwrite\Platform\Modules\Sites\Http\Variables\XList as ListVariables;
use Utopia\Platform\Service;
class Http extends Service

View file

@ -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;
}
}
}

View file

@ -201,7 +201,7 @@ abstract class Format
case 'sites':
switch ($method) {
case 'getUsage':
case 'getSiteUsage':
case 'listUsage':
switch ($param) {
case 'range':
return 'SiteUsageRange';

View file

@ -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,

View file

@ -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,