Fix API spec metadata and summaries (#12544)

This commit is contained in:
Chirag Aggarwal authored and GitHub committed 2026-06-09 10:25:35 +05:30
1 parent 9fc824cc42
commit 0d3dddfe97
21 files changed
+275 -23

No files matched your search

+112
View File
@@ -85,6 +85,48 @@ return [
'icon' => '/images/services/databases.png',
'platforms' => ['client', 'server', 'console'],
],
'documentsDB' => [
'key' => 'documentsDB',
'name' => 'DocumentsDB',
'subtitle' => 'The DocumentsDB service allows you to create structured collections of documents, query and filter lists of documents.',
'description' => '/docs/services/databases.md',
'controller' => '', // Uses modules
'sdk' => true,
'docs' => true,
'docsUrl' => 'https://appwrite.io/docs/references/documentsdb',
'tests' => false,
'optional' => true,
'icon' => '/images/services/databases.png',
'platforms' => ['server', 'console'],
],
'tablesDB' => [
'key' => 'tablesDB',
'name' => 'TablesDB',
'subtitle' => 'The TablesDB service allows you to create structured tables of columns, query and filter lists of rows.',
'description' => '/docs/services/tablesdb.md',
'controller' => '', // Uses modules
'sdk' => true,
'docs' => true,
'docsUrl' => 'https://appwrite.io/docs/references/tablesdb',
'tests' => false,
'optional' => true,
'icon' => '/images/services/databases.png',
'platforms' => ['server', 'console'],
],
'vectorsDB' => [
'key' => 'vectorsDB',
'name' => 'VectorsDB',
'subtitle' => 'The VectorsDB service allows you to create vector collections, embeddings, indexes, and documents.',
'description' => '/docs/services/databases.md',
'controller' => '', // Uses modules
'sdk' => true,
'docs' => true,
'docsUrl' => 'https://appwrite.io/docs/references/vectorsdb',
'tests' => false,
'optional' => true,
'icon' => '/images/services/databases.png',
'platforms' => ['server', 'console'],
],
'locale' => [
'key' => 'locale',
'name' => 'Locale',
@@ -197,6 +239,48 @@ return [
'icon' => '',
'platforms' => ['client', 'server', 'console'],
],
'webhooks' => [
'key' => 'webhooks',
'name' => 'Webhooks',
'subtitle' => 'The Webhooks service allows you to configure event-driven HTTP callbacks for your project.',
'description' => '',
'controller' => '', // Uses modules
'sdk' => true,
'docs' => true,
'docsUrl' => '',
'tests' => false,
'optional' => true,
'icon' => '',
'platforms' => ['server', 'console'],
],
'tokens' => [
'key' => 'tokens',
'name' => 'Tokens',
'subtitle' => 'The Tokens service allows you to create and manage resource tokens for project resources.',
'description' => '',
'controller' => '', // Uses modules
'sdk' => true,
'docs' => true,
'docsUrl' => '',
'tests' => false,
'optional' => true,
'icon' => '',
'platforms' => ['server', 'console'],
],
'presences' => [
'key' => 'presences',
'name' => 'Presences',
'subtitle' => 'The Presences service allows you to create, query, and manage realtime presence state.',
'description' => '',
'controller' => '', // Uses modules
'sdk' => true,
'docs' => true,
'docsUrl' => 'https://appwrite.io/docs/references/presences',
'tests' => false,
'optional' => true,
'icon' => '',
'platforms' => ['client', 'server', 'console'],
],
'sites' => [
'key' => 'sites',
'name' => 'Sites',
@@ -281,6 +365,34 @@ return [
'icon' => '',
'platforms' => ['client', 'server', 'console'],
],
'assistant' => [
'key' => 'assistant',
'name' => 'Assistant',
'subtitle' => 'The Assistant service allows Console users to ask assistant queries.',
'description' => '',
'controller' => '', // Uses modules
'sdk' => true,
'docs' => true,
'docsUrl' => 'https://appwrite.io/docs/references/assistant',
'tests' => false,
'optional' => false,
'icon' => '',
'platforms' => ['console'],
],
'organization' => [
'key' => 'organization',
'name' => 'Organization',
'subtitle' => 'The Organization service allows you to manage organization-level projects.',
'description' => '',
'controller' => '', // Uses modules
'sdk' => true,
'docs' => true,
'docsUrl' => '',
'tests' => false,
'optional' => false,
'icon' => '',
'platforms' => ['server', 'console'],
],
'migrations' => [
'key' => 'migrations',
'name' => 'Migrations',
+5 -4
View File
@@ -29,6 +29,7 @@ use Appwrite\SDK\Deprecated;
use Appwrite\SDK\Method;
use Appwrite\SDK\MethodType;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Template\Template;
use Appwrite\URL\URL as URLParser;
use Appwrite\Usage\Context;
@@ -257,7 +258,7 @@ Http::post('/v1/account')
->label('abuse-limit', 10)
->param('userId', '', fn (Database $dbForProject) => new CustomId(false, $dbForProject->getAdapter()->getMaxUIDLength()), 'User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.', false, ['dbForProject'])
->param('email', '', new EmailValidator(), 'User email.')
->param('password', '', fn ($project, $passwordsDictionary) => new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? []), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false)], Validator::TYPE_STRING), 'New user password. Must be between 8 and 256 chars.', false, ['project', 'passwordsDictionary'])
->param('password', '', fn ($project, $passwordsDictionary) => new PasswordFormat(new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? []), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false)], Validator::TYPE_STRING)), 'New user password. Must be between 8 and 256 chars.', false, ['project', 'passwordsDictionary'])
->param('name', '', new Text(128), 'User name. Max length: 128 chars.', true)
->inject('request')
->inject('response')
@@ -3273,8 +3274,8 @@ Http::patch('/v1/account/password')
contentType: ContentType::JSON
))
->label('abuse-limit', 10)
->param('password', '', fn ($project, $passwordsDictionary) => new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? []), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false)], Validator::TYPE_STRING), 'New user password. Must be at least 8 chars.', false, ['project', 'passwordsDictionary'])
->param('oldPassword', '', new Text(256, 0), 'Current user password. Max length: 256 chars.', true)
->param('password', '', fn ($project, $passwordsDictionary) => new PasswordFormat(new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? []), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false)], Validator::TYPE_STRING)), 'New user password. Must be at least 8 chars.', false, ['project', 'passwordsDictionary'])
->param('oldPassword', '', new PasswordFormat(new Text(256, 0)), 'Current user password. Max length: 256 chars.', true)
->inject('response')
->inject('user')
->inject('project')
@@ -3890,7 +3891,7 @@ Http::put('/v1/account/recovery')
->label('abuse-key', 'url:{url},userId:{param-userId}')
->param('userId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'User ID.', false, ['dbForProject'])
->param('secret', '', new Text(256), 'Valid reset token.')
->param('password', '', fn ($project, $passwordsDictionary) => new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? []), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false)], Validator::TYPE_STRING), 'New user password. Must be between 8 and 256 chars.', false, ['project', 'passwordsDictionary'])
->param('password', '', fn ($project, $passwordsDictionary) => new PasswordFormat(new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? []), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false)], Validator::TYPE_STRING)), 'New user password. Must be between 8 and 256 chars.', false, ['project', 'passwordsDictionary'])
->inject('response')
->inject('user')
->inject('dbForProject')
+3 -2
View File
@@ -17,6 +17,7 @@ use Appwrite\SDK\ContentType;
use Appwrite\SDK\Deprecated;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Database\Validator\CompoundUID;
use Appwrite\Utopia\Database\Validator\CustomId;
use Appwrite\Utopia\Database\Validator\Queries\Messages;
@@ -458,7 +459,7 @@ Http::post('/v1/messaging/providers/smtp')
->param('host', '', new Text(0), 'SMTP hosts. Either a single hostname or multiple semicolon-delimited hostnames. You can also specify a different port for each host such as `smtp1.example.com:25;smtp2.example.com`. You can also specify encryption type, for example: `tls://smtp1.example.com:587;ssl://smtp2.example.com:465"`. Hosts will be tried in order.')
->param('port', 587, new Range(1, 65535), 'The default SMTP server port.', true)
->param('username', '', new Text(0), 'Authentication username.', true)
->param('password', '', new Text(0), 'Authentication password.', true)
->param('password', '', new PasswordFormat(new Text(0)), 'Authentication password.', true)
->param('encryption', '', new WhiteList(['none', 'ssl', 'tls']), 'Encryption type. Can be omitted, \'ssl\', or \'tls\'', true, enum: new Enum(name: 'SmtpEncryption'))
->param('autoTLS', true, new Boolean(), 'Enable SMTP AutoTLS feature.', true)
->param('mailer', '', new Text(0), 'The value to use for the X-Mailer header.', true)
@@ -1809,7 +1810,7 @@ Http::patch('/v1/messaging/providers/smtp/:providerId')
->param('host', '', new Text(0), 'SMTP hosts. Either a single hostname or multiple semicolon-delimited hostnames. You can also specify a different port for each host such as `smtp1.example.com:25;smtp2.example.com`. You can also specify encryption type, for example: `tls://smtp1.example.com:587;ssl://smtp2.example.com:465"`. Hosts will be tried in order.', true)
->param('port', null, new Nullable(new Range(1, 65535)), 'SMTP port.', true)
->param('username', '', new Text(0), 'Authentication username.', true)
->param('password', '', new Text(0), 'Authentication password.', true)
->param('password', '', new PasswordFormat(new Text(0)), 'Authentication password.', true)
->param('encryption', '', new WhiteList(['none', 'ssl', 'tls']), 'Encryption type. Can be \'ssl\' or \'tls\'', true, enum: new Enum(name: 'SmtpEncryption'))
->param('autoTLS', null, new Nullable(new Boolean()), 'Enable SMTP AutoTLS feature.', true)
->param('mailer', '', new Text(0), 'The value to use for the X-Mailer header.', true)
+3 -2
View File
@@ -22,6 +22,7 @@ use Appwrite\SDK\ContentType;
use Appwrite\SDK\Deprecated;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Database\Validator\CustomId;
use Appwrite\Utopia\Database\Validator\Queries\Identities;
use Appwrite\Utopia\Database\Validator\Queries\Memberships;
@@ -283,7 +284,7 @@ Http::post('/v1/users')
->param('userId', '', fn (Database $dbForProject) => new CustomId(false, $dbForProject->getAdapter()->getMaxUIDLength()), 'User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.', false, ['dbForProject'])
->param('email', null, new Nullable(new EmailValidator()), 'User email.', true)
->param('phone', null, new Nullable(new Phone()), 'Phone number. Format this number with a leading \'+\' and a country code, e.g., +16175551212.', true)
->param('password', '', fn ($project, $passwordsDictionary) => new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? []), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false)], Validator::TYPE_STRING), 'Plain text user password. Must be at least 8 chars.', true, ['project', 'passwordsDictionary'])
->param('password', '', fn ($project, $passwordsDictionary) => new PasswordFormat(new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? []), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false)], Validator::TYPE_STRING)), 'Plain text user password. Must be at least 8 chars.', true, ['project', 'passwordsDictionary'])
->param('name', '', new Text(128), 'User name. Max length: 128 chars.', true)
->inject('response')
->inject('project')
@@ -1434,7 +1435,7 @@ Http::patch('/v1/users/:userId/password')
]
))
->param('userId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'User ID.', false, ['dbForProject'])
->param('password', '', fn ($project, $passwordsDictionary) => new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? [], allowEmpty: true), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false, allowEmpty: true)], Validator::TYPE_STRING), 'New user password. Must be at least 8 chars.', false, ['project', 'passwordsDictionary'])
->param('password', '', fn ($project, $passwordsDictionary) => new PasswordFormat(new AllOf([new PasswordStrength($project->getAttribute('auths', [])['passwordStrength'] ?? [], allowEmpty: true), new PasswordDictionary($passwordsDictionary, enabled: $project->getAttribute('auths', [])['passwordDictionary'] ?? false, allowEmpty: true)], Validator::TYPE_STRING)), 'New user password. Must be at least 8 chars.', false, ['project', 'passwordsDictionary'])
->inject('response')
->inject('project')
->inject('dbForProject')
@@ -33,7 +33,7 @@ class Update extends DatetimeUpdate
$this
->setHttpMethod(self::HTTP_REQUEST_METHOD_PATCH)
->setHttpPath('/v1/tablesdb/:databaseId/tables/:tableId/columns/datetime/:key')
->desc('Update dateTime column')
->desc('Update datetime column')
->groups(['api', 'database', 'schema'])
->label('scope', ['tables.write', 'collections.write', 'columns.write', 'attributes.write'])
->label('resourceType', RESOURCE_TYPE_DATABASES)
@@ -44,7 +44,7 @@ class Create extends CreateDocumentAction
$this
->setHttpMethod(self::HTTP_REQUEST_METHOD_POST)
->setHttpPath('/v1/vectorsdb/embeddings/text')
->desc('Create Text Embeddings')
->desc('Create text embeddings')
->groups(['api', 'database'])
->label('scope', 'documents.write')
->label('resourceType', RESOURCE_TYPE_EMBEDDINGS_TEXT)
@@ -9,6 +9,7 @@ use Appwrite\Platform\Action;
use Appwrite\SDK\AuthType;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Response;
use Utopia\Database\Database;
use Utopia\Database\Document;
@@ -60,7 +61,7 @@ class Create extends Action
->param('adminSecret', '', new Text(512), 'Source\'s Admin Secret')
->param('database', '', new Text(512), 'Source\'s Database Name')
->param('username', '', new Text(512), 'Source\'s Database Username')
->param('password', '', new Text(512), 'Source\'s Database Password')
->param('password', '', new PasswordFormat(new Text(512)), 'Source\'s Database Password')
->param('port', 5432, new Integer(true), 'Source\'s Database Port', true)
->inject('response')
->inject('dbForProject')
@@ -7,6 +7,7 @@ use Appwrite\Platform\Action;
use Appwrite\SDK\AuthType;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Response;
use Utopia\Database\Document;
use Utopia\Migration\Sources\NHost;
@@ -53,7 +54,7 @@ class Get extends Action
->param('adminSecret', '', new Text(512), 'Source\'s Admin Secret.')
->param('database', '', new Text(512), 'Source\'s Database Name.')
->param('username', '', new Text(512), 'Source\'s Database Username.')
->param('password', '', new Text(512), 'Source\'s Database Password.')
->param('password', '', new PasswordFormat(new Text(512)), 'Source\'s Database Password.')
->param('port', 5432, new Integer(true), 'Source\'s Database Port.', true)
->inject('response')
->callback($this->action(...));
@@ -9,6 +9,7 @@ use Appwrite\Platform\Action;
use Appwrite\SDK\AuthType;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Response;
use Utopia\Database\Database;
use Utopia\Database\Document;
@@ -60,7 +61,7 @@ class Create extends Action
->param('apiKey', '', new Text(512), 'Source\'s API Key')
->param('databaseHost', '', new Text(512), 'Source\'s Database Host')
->param('username', '', new Text(512), 'Source\'s Database Username')
->param('password', '', new Text(512), 'Source\'s Database Password')
->param('password', '', new PasswordFormat(new Text(512)), 'Source\'s Database Password')
->param('port', 5432, new Integer(true), 'Source\'s Database Port', true)
->inject('response')
->inject('dbForProject')
@@ -7,6 +7,7 @@ use Appwrite\Platform\Action;
use Appwrite\SDK\AuthType;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Response;
use Utopia\Database\Document;
use Utopia\Migration\Sources\Supabase;
@@ -53,7 +54,7 @@ class Get extends Action
->param('apiKey', '', new Text(512), 'Source\'s API Key.')
->param('databaseHost', '', new Text(512), 'Source\'s Database Host.')
->param('username', '', new Text(512), 'Source\'s Database Username.')
->param('password', '', new Text(512), 'Source\'s Database Password.')
->param('password', '', new PasswordFormat(new Text(512)), 'Source\'s Database Password.')
->param('port', 5432, new Integer(true), 'Source\'s Database Port.', true)
->inject('response')
->callback($this->action(...));
@@ -10,6 +10,7 @@ use Appwrite\SDK\AuthType;
use Appwrite\SDK\ContentType;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Template\Template;
use Appwrite\Utopia\Response;
use Appwrite\Utopia\Response as UtopiaResponse;
@@ -64,7 +65,7 @@ class Create extends Action
->param('host', '', new Hostname(), 'SMTP server host name', optional: true, deprecated: true) // Backwards compatibility
->param('port', null, new Integer(), 'SMTP server port', optional: true, deprecated: true) // Backwards compatibility
->param('username', '', new Text(256), 'SMTP server username', optional: true, deprecated: true) // Backwards compatibility
->param('password', '', new Text(256), 'SMTP server password', optional: true, deprecated: true) // Backwards compatibility
->param('password', '', new PasswordFormat(new Text(256)), 'SMTP server password', optional: true, deprecated: true) // Backwards compatibility
->param('secure', '', new WhiteList(['tls', 'ssl'], true), 'Does SMTP server use secure connection', optional: true, deprecated: true) // Backwards compatibility
->inject('response')
->inject('project')
@@ -7,6 +7,7 @@ use Appwrite\Platform\Action;
use Appwrite\SDK\AuthType;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Response;
use PHPMailer\PHPMailer\PHPMailer;
use Throwable;
@@ -62,7 +63,7 @@ class Update extends Action
->param('host', null, new Nullable(new Hostname()), 'SMTP server hostname (domain)', optional: true)
->param('port', null, new Nullable(new Integer()), 'SMTP server port', optional: true)
->param('username', null, new Nullable(new Text(256, 0)), 'SMTP server username. Pass an empty string to clear a previously set value.', optional: true)
->param('password', null, new Nullable(new Text(256, 0)), 'SMTP server password. Pass an empty string to clear a previously set value. This property is stored securely and cannot be read in future (write-only).', optional: true)
->param('password', null, new Nullable(new PasswordFormat(new Text(256, 0))), 'SMTP server password. Pass an empty string to clear a previously set value. This property is stored securely and cannot be read in future (write-only).', optional: true)
->param('senderEmail', null, new Nullable(new Email(allowEmpty: true)), 'Email address shown in inbox as the sender of the email. Pass an empty string to clear a previously set value.', optional: true)
->param('senderName', null, new Nullable(new Text(256, 0)), 'Name shown in inbox as the sender of the email. Pass an empty string to clear a previously set value.', optional: true)
->param('replyToEmail', null, new Nullable(new Email(allowEmpty: true)), 'Email used when user replies to the email. Pass an empty string to clear a previously set value.', optional: true)
@@ -40,7 +40,7 @@ class Create extends Action
->setHttpMethod(Action::HTTP_REQUEST_METHOD_POST)
->setHttpPath('/v1/proxy/rules/redirect')
->groups(['api', 'proxy'])
->desc('Create Redirect rule')
->desc('Create redirect rule')
->label('scope', 'rules.write')
->label('event', 'rules.[ruleId].create')
->label('audits.event', 'rule.create')
@@ -8,6 +8,7 @@ use Appwrite\Extend\Exception;
use Appwrite\SDK\AuthType;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Database\Validator\CustomId;
use Appwrite\Utopia\Response;
use Utopia\Database\Database;
@@ -68,7 +69,7 @@ class Create extends Action
->param('enabled', true, new Boolean(), 'Enable or disable a webhook.', true)
->param('tls', false, new Boolean(), 'Certificate verification, false for disabled or true for enabled.', true)
->param('authUsername', '', new Text(256), 'Webhook HTTP user. Max length: 256 chars.', true)
->param('authPassword', '', new Text(256), 'Webhook HTTP password. Max length: 256 chars.', true)
->param('authPassword', '', new PasswordFormat(new Text(256)), 'Webhook HTTP password. Max length: 256 chars.', true)
->param('secret', null, new Nullable(new Text(256, 8)), 'Webhook secret key. If not provided, a new key will be generated automatically. Key must be at least 8 characters long, and at max 256 characters.', optional: true)
->inject('response')
->inject('project')
@@ -8,6 +8,7 @@ use Appwrite\Extend\Exception;
use Appwrite\SDK\AuthType;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Response;
use Utopia\Database\Database;
use Utopia\Database\Document;
@@ -65,7 +66,7 @@ class Update extends Action
->param('enabled', true, new Boolean(), 'Enable or disable a webhook.', true)
->param('tls', false, new Boolean(), 'Certificate verification, false for disabled or true for enabled.', true)
->param('authUsername', '', new Text(256), 'Webhook HTTP user. Max length: 256 chars.', true)
->param('authPassword', '', new Text(256), 'Webhook HTTP password. Max length: 256 chars.', true)
->param('authPassword', '', new PasswordFormat(new Text(256)), 'Webhook HTTP password. Max length: 256 chars.', true)
->inject('response')
->inject('project')
->inject('queueForEvents')
@@ -492,6 +492,9 @@ class OpenAPI3 extends Format
$node['schema']['x-upload-id'] = true;
}
$node['schema']['type'] = $validator->getType();
$node['schema']['x-appwrite'] = [
'idGenerator' => 'ID.unique',
];
$node['schema']['x-example'] = ($param['example'] ?? '') ?: '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
break;
case \Utopia\Database\Validator\Datetime::class:
@@ -597,6 +600,7 @@ class OpenAPI3 extends Format
$node['schema']['x-example'] = ($param['example'] ?? '') ?: '["' . Role::any()->toString() . '"]';
break;
case \Appwrite\Auth\Validator\Password::class:
case \Appwrite\SDK\Specification\Validator\PasswordFormat::class:
$node['schema']['type'] = $validator->getType();
$node['schema']['format'] = 'password';
$node['schema']['x-example'] = ($param['example'] ?? '') ?: 'password';
@@ -817,6 +821,10 @@ class OpenAPI3 extends Format
$body['content'][$consumes[0]]['schema']['properties'][$name]['x-upload-id'] = $node['schema']['x-upload-id'];
}
if (isset($node['schema']['x-appwrite'])) {
$body['content'][$consumes[0]]['schema']['properties'][$name]['x-appwrite'] = $node['schema']['x-appwrite'];
}
if (\array_key_exists('items', $node['schema'])) {
$body['content'][$consumes[0]]['schema']['properties'][$name]['items'] = $node['schema']['items'];
}
@@ -883,7 +891,7 @@ class OpenAPI3 extends Format
}
$type = '';
$format = null;
$format = $rule['format'] ?? null;
$items = null;
$examples[$name] = $rule['example'] ?? null;
@@ -474,6 +474,9 @@ class Swagger2 extends Format
$node['x-upload-id'] = true;
}
$node['type'] = $validator->getType();
$node['x-appwrite'] = [
'idGenerator' => 'ID.unique',
];
$node['x-example'] = ($param['example'] ?? '') ?: '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
break;
case \Utopia\Database\Validator\Datetime::class:
@@ -563,6 +566,7 @@ class Swagger2 extends Format
$node['x-example'] = ($param['example'] ?? '') ?: '["' . Role::any()->toString() . '"]';
break;
case \Appwrite\Auth\Validator\Password::class:
case \Appwrite\SDK\Specification\Validator\PasswordFormat::class:
$node['type'] = $validator->getType();
$node['format'] = 'password';
$node['x-example'] = ($param['example'] ?? '') ?: 'password';
@@ -778,6 +782,10 @@ class Swagger2 extends Format
$body['schema']['properties'][$name]['x-enum-keys'] = $node['x-enum-keys'];
}
if (isset($node['x-appwrite'])) {
$body['schema']['properties'][$name]['x-appwrite'] = $node['x-appwrite'];
}
if ($parameter['nullable']) {
$body['schema']['properties'][$name]['x-nullable'] = true;
}
@@ -846,7 +854,7 @@ class Swagger2 extends Format
}
$type = '';
$format = null;
$format = $rule['format'] ?? null;
$items = null;
$examples[$name] = $rule['example'] ?? null;
@@ -0,0 +1,32 @@
<?php
namespace Appwrite\SDK\Specification\Validator;
use Utopia\Validator;
class PasswordFormat extends Validator
{
public function __construct(private Validator $validator)
{
}
public function getDescription(): string
{
return $this->validator->getDescription();
}
public function isArray(): bool
{
return $this->validator->isArray();
}
public function getType(): string
{
return $this->validator->getType();
}
public function isValid(mixed $value): bool
{
return $this->validator->isValid($value);
}
}
@@ -111,9 +111,10 @@ class Project extends Model
])
->addRule('smtpPassword', [
'type' => self::TYPE_STRING,
'format' => 'password',
'description' => 'SMTP server password. This property is write-only and always returned empty.',
'default' => '',
'example' => '',
'example' => 'smtp-password',
])
->addRule('smtpSecure', [
'type' => self::TYPE_STRING,
@@ -65,9 +65,10 @@ class Webhook extends Model
])
->addRule('authPassword', [
'type' => self::TYPE_STRING,
'format' => 'password',
'description' => 'HTTP basic authentication password.',
'default' => '',
'example' => 'password',
'example' => 'webhook-password',
])
->addRule('secret', [
'type' => self::TYPE_STRING,
@@ -2,7 +2,14 @@
namespace Tests\Unit\SDK\Specification;
use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Format;
use Appwrite\SDK\Specification\Format\OpenAPI3;
use Appwrite\SDK\Specification\Format\Swagger2;
use Appwrite\SDK\Specification\Validator\PasswordFormat;
use Appwrite\Utopia\Database\Validator\CustomId;
use Appwrite\Utopia\Response;
use Appwrite\Utopia\Response\Model\HealthStatus;
use Appwrite\Utopia\Response\Model\PlatformAndroid;
use Appwrite\Utopia\Response\Model\PlatformApple;
@@ -10,8 +17,12 @@ use Appwrite\Utopia\Response\Model\PlatformLinux;
use Appwrite\Utopia\Response\Model\PlatformList;
use Appwrite\Utopia\Response\Model\PlatformWeb;
use Appwrite\Utopia\Response\Model\PlatformWindows;
use Appwrite\Utopia\Response\Model\Webhook;
use PHPUnit\Framework\TestCase;
use Utopia\DI\Container;
use Utopia\Http\Route;
use Utopia\Validator\Nullable;
use Utopia\Validator\Text;
class TestFormat extends Format
{
@@ -76,4 +87,72 @@ final class FormatTest extends TestCase
{
$this->assertSame('HealthCheckStatus', (new HealthStatus())->getRules()['status']['enumSDKName']);
}
public function testOpenApiCustomIdBodyFieldIncludesIdGeneratorMetadata(): void
{
Method::$processed = [];
Method::$errors = [];
$route = (new Route('POST', '/v1/tests'))
->desc('Create test')
->label('sdk', new Method(
namespace: 'test',
group: null,
name: 'createTest',
description: 'Create test.',
auth: [],
responses: [],
))
->param('userId', '', new CustomId(), 'User ID.');
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$this->assertSame(
['idGenerator' => 'ID.unique'],
$spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties']['userId']['x-appwrite']
);
}
public function testPasswordFormatMarksOnlyExplicitPasswordFields(): void
{
Method::$processed = [];
Method::$errors = [];
$route = (new Route('POST', '/v1/tests'))
->desc('Create test')
->label('sdk', new Method(
namespace: 'test',
group: null,
name: 'createTest',
description: 'Create test.',
auth: [],
responses: [
new SDKResponse(
code: 200,
model: Response::MODEL_WEBHOOK,
),
],
))
->param('password', '', new PasswordFormat(new Text(256)), 'Password.')
->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();
$swagger = (new Swagger2(new Container(), [], [$route], [new Webhook()], [], 0, 'console'))->parse();
$openApiProperties = $openApi['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties'];
$swaggerProperties = $swagger['paths']['/tests']['post']['parameters'][0]['schema']['properties'];
$this->assertSame('password', $openApiProperties['password']['format']);
$this->assertSame('password', $openApiProperties['nullablePassword']['format']);
$this->assertTrue($openApiProperties['nullablePassword']['x-nullable']);
$this->assertArrayNotHasKey('format', $openApiProperties['name']);
$this->assertSame('password', $openApi['components']['schemas']['webhook']['properties']['authPassword']['format']);
$this->assertSame('password', $swaggerProperties['password']['format']);
$this->assertSame('password', $swaggerProperties['nullablePassword']['format']);
$this->assertTrue($swaggerProperties['nullablePassword']['x-nullable']);
$this->assertArrayNotHasKey('format', $swaggerProperties['name']);
$this->assertSame('password', $swagger['definitions']['webhook']['properties']['authPassword']['format']);
}
}