Appwrite/appwrite
1
0
Fork 0
mirror of https://github.com/appwrite/appwrite.git synced 2026-05-26 13:51:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: better examples

Browse Source
This commit is contained in:
Chirag Aggarwal
2025-12-01 19:21:49 +05:30
parent 6aa054bc7c
commit aaafdaae52
37 changed files with 2662 additions and 2507 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Appwrite/SDK/Specification/Format/OpenAPI3.php
+45 -26
View File
@@ -449,23 +449,23 @@ class OpenAPI3 extends Format
case 'Utopia\Database\Validator\UID':
case 'Utopia\Validator\Text':
$node['schema']['type'] = $validator->getType();
$node['schema']['x-example'] = '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
$node['schema']['x-example'] = ($param['example'] ?? '') ?: '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
break;
case 'Utopia\Validator\Boolean':
$node['schema']['type'] = $validator->getType();
$node['schema']['x-example'] = false;
$node['schema']['x-example'] = ($param['example'] ?? '') ?: false;
break;
case 'Appwrite\Utopia\Database\Validator\CustomId':
if ($sdk->getType() === MethodType::UPLOAD) {
$node['schema']['x-upload-id'] = true;
}
$node['schema']['type'] = $validator->getType();
$node['schema']['x-example'] = '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
$node['schema']['x-example'] = ($param['example'] ?? '') ?: '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
break;
case 'Utopia\Database\Validator\DatetimeValidator':
$node['schema']['type'] = $validator->getType();
$node['schema']['format'] = 'datetime';
$node['schema']['x-example'] = Model::TYPE_DATETIME_EXAMPLE;
$node['schema']['x-example'] = ($param['example'] ?? '') ?: Model::TYPE_DATETIME_EXAMPLE;
break;
case 'Utopia\Database\Validator\Spatial':
/** @var Spatial $validator */
@@ -475,7 +475,7 @@ class OpenAPI3 extends Format
['type' => 'array']
]
];
$node['schema']['x-example'] = match ($validator->getSpatialType()) {
$node['schema']['x-example'] = ($param['example'] ?? '') ?: match ($validator->getSpatialType()) {
Database::VAR_POINT => '[1, 2]',
Database::VAR_LINESTRING => '[[1, 2], [3, 4], [5, 6]]',
Database::VAR_POLYGON => '[[[1, 2], [3, 4], [5, 6], [1, 2]]]',
@@ -484,14 +484,14 @@ class OpenAPI3 extends Format
case 'Appwrite\Network\Validator\Email':
$node['schema']['type'] = $validator->getType();
$node['schema']['format'] = 'email';
$node['schema']['x-example'] = 'email@example.com';
$node['schema']['x-example'] = ($param['example'] ?? '') ?: 'email@example.com';
break;
case 'Utopia\Validator\Host':
case 'Utopia\Validator\URL':
case 'Appwrite\Network\Validator\Redirect':
$node['schema']['type'] = $validator->getType();
$node['schema']['format'] = 'url';
$node['schema']['x-example'] = 'https://example.com';
$node['schema']['x-example'] = ($param['example'] ?? '') ?: 'https://example.com';
break;
case 'Utopia\Validator\JSON':
case 'Utopia\Validator\Mock':
@@ -511,6 +511,9 @@ class OpenAPI3 extends Format
$node['schema']['items'] = [
'type' => $validator->getValidator()->getType(),
];
if (!empty($param['example'])) {
$node['schema']['x-example'] = $param['example'];
}
break;
case 'Appwrite\Utopia\Database\Validator\Queries\Base':
case 'Appwrite\Utopia\Database\Validator\Queries\Columns':
@@ -551,47 +554,56 @@ class OpenAPI3 extends Format
$node['schema']['items'] = [
'type' => 'string',
];
$node['schema']['x-example'] = '["' . Permission::read(Role::any()) . '"]';
$node['schema']['x-example'] = ($param['example'] ?? '') ?: '["' . Permission::read(Role::any()) . '"]';
break;
case 'Utopia\Database\Validator\Roles':
$node['schema']['type'] = $validator->getType();
$node['schema']['items'] = [
'type' => 'string',
];
$node['schema']['x-example'] = '["' . Role::any()->toString() . '"]';
$node['schema']['x-example'] = ($param['example'] ?? '') ?: '["' . Role::any()->toString() . '"]';
break;
case 'Appwrite\Auth\Validator\Password':
$node['schema']['type'] = $validator->getType();
$node['schema']['format'] = 'password';
$node['schema']['x-example'] = 'password';
$node['schema']['x-example'] = ($param['example'] ?? '') ?: 'password';
break;
case 'Appwrite\Auth\Validator\Phone':
$node['schema']['type'] = $validator->getType();
$node['schema']['format'] = 'phone';
$node['schema']['x-example'] = '+12065550100'; // In the US, 555 is reserved like example.com
$node['schema']['x-example'] = ($param['example'] ?? '') ?: '+12065550100'; // In the US, 555 is reserved like example.com
break;
case 'Utopia\Validator\Range':
/** @var Range $validator */
$node['schema']['type'] = $validator->getType() === Validator::TYPE_FLOAT ? 'number' : $validator->getType();
$node['schema']['format'] = $validator->getType() == Validator::TYPE_INTEGER ? 'int32' : 'float';
$node['schema']['x-example'] = $validator->getMin();
$node['schema']['x-example'] = ($param['example'] ?? '') ?: $validator->getMin();
break;
case 'Utopia\Validator\Integer':
$node['schema']['type'] = $validator->getType();
$node['schema']['format'] = 'int32';
if (!empty($param['example'])) {
$node['schema']['x-example'] = $param['example'];
}
break;
case 'Utopia\Validator\Numeric':
case 'Utopia\Validator\FloatValidator':
$node['schema']['type'] = 'number';
$node['schema']['format'] = 'float';
if (!empty($param['example'])) {
$node['schema']['x-example'] = $param['example'];
}
break;
case 'Utopia\Validator\Length':
$node['schema']['type'] = $validator->getType();
if (!empty($param['example'])) {
$node['schema']['x-example'] = $param['example'];
}
break;
case 'Utopia\Validator\WhiteList':
/** @var WhiteList $validator */
$node['schema']['type'] = $validator->getType();
$node['schema']['x-example'] = $validator->getList()[0];
$node['schema']['x-example'] = ($param['example'] ?? '') ?: $validator->getList()[0];
// Iterate from the blackList. If it matches with the current one, then it is a blackList
// Do not add the enum
@@ -617,7 +629,7 @@ class OpenAPI3 extends Format
break;
case 'Appwrite\Utopia\Database\Validator\CompoundUID':
$node['schema']['type'] = $validator->getType();
$node['schema']['x-example'] = '<ID1:ID2>';
$node['schema']['x-example'] = ($param['example'] ?? '') ?: '<ID1:ID2>';
break;
case 'Appwrite\Utopia\Database\Validator\Operation':
if ($array) {
@@ -633,22 +645,29 @@ class OpenAPI3 extends Format
} else {
$node['schema']['type'] = 'object';
}
$example = [
'action' => 'create',
'databaseId' => '<DATABASE_ID>',
$collectionIdKey => '<'.\strtoupper(Template::fromCamelCaseToSnake($collectionIdKey)).'>',
$documentIdKey => '<'.\strtoupper(Template::fromCamelCaseToSnake($documentIdKey)).'>',
'data' => [
'name' => 'Walter O\'Brien',
],
];
if ($array) {
$example = [$example];
if (empty($param['example'])) {
$example = [
'action' => 'create',
'databaseId' => '<DATABASE_ID>',
$collectionIdKey => '<'.\strtoupper(Template::fromCamelCaseToSnake($collectionIdKey)).'>',
$documentIdKey => '<'.\strtoupper(Template::fromCamelCaseToSnake($documentIdKey)).'>',
'data' => [
'name' => 'Walter O\'Brien',
],
];
if ($array) {
$example = [$example];
}
$node['schema']['x-example'] = \str_replace("\n", "\n\t", \json_encode($example, JSON_PRETTY_PRINT));
} else {
$node['schema']['x-example'] = $param['example'];
}
$node['schema']['x-example'] = \str_replace("\n", "\n\t", \json_encode($example, JSON_PRETTY_PRINT));
break;
default:
$node['schema']['type'] = 'string';
if (!empty($param['example'])) {
$node['schema']['x-example'] = $param['example'];
}
break;
}
src/Appwrite/SDK/Specification/Format/Swagger2.php
+45 -26
View File
@@ -454,23 +454,23 @@ class Swagger2 extends Format
case 'Utopia\Validator\Text':
case 'Utopia\Database\Validator\UID':
$node['type'] = $validator->getType();
$node['x-example'] = '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
$node['x-example'] = ($param['example'] ?? '') ?: '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
break;
case 'Utopia\Validator\Boolean':
$node['type'] = $validator->getType();
$node['x-example'] = false;
$node['x-example'] = ($param['example'] ?? '') ?: false;
break;
case 'Appwrite\Utopia\Database\Validator\CustomId':
if ($sdk->getType() === MethodType::UPLOAD) {
$node['x-upload-id'] = true;
}
$node['type'] = $validator->getType();
$node['x-example'] = '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
$node['x-example'] = ($param['example'] ?? '') ?: '<' . \strtoupper(Template::fromCamelCaseToSnake($node['name'])) . '>';
break;
case 'Utopia\Database\Validator\DatetimeValidator':
$node['type'] = $validator->getType();
$node['format'] = 'datetime';
$node['x-example'] = Model::TYPE_DATETIME_EXAMPLE;
$node['x-example'] = ($param['example'] ?? '') ?: Model::TYPE_DATETIME_EXAMPLE;
break;
case 'Utopia\Database\Validator\Spatial':
/** @var Spatial $validator */
@@ -480,7 +480,7 @@ class Swagger2 extends Format
['type' => 'array']
]
];
$node['x-example'] = match ($validator->getSpatialType()) {
$node['x-example'] = ($param['example'] ?? '') ?: match ($validator->getSpatialType()) {
Database::VAR_POINT => '[1, 2]',
Database::VAR_LINESTRING => '[[1, 2], [3, 4], [5, 6]]',
Database::VAR_POLYGON => '[[[1, 2], [3, 4], [5, 6], [1, 2]]]',
@@ -489,14 +489,14 @@ class Swagger2 extends Format
case 'Appwrite\Network\Validator\Email':
$node['type'] = $validator->getType();
$node['format'] = 'email';
$node['x-example'] = 'email@example.com';
$node['x-example'] = ($param['example'] ?? '') ?: 'email@example.com';
break;
case 'Utopia\Validator\Host':
case 'Utopia\Validator\URL':
case 'Appwrite\Network\Validator\Redirect':
$node['type'] = $validator->getType();
$node['format'] = 'url';
$node['x-example'] = 'https://example.com';
$node['x-example'] = ($param['example'] ?? '') ?: 'https://example.com';
break;
case 'Utopia\Validator\ArrayList':
/** @var ArrayList $validator */
@@ -505,6 +505,9 @@ class Swagger2 extends Format
$node['items'] = [
'type' => $validator->getValidator()->getType(),
];
if (!empty($param['example'])) {
$node['x-example'] = $param['example'];
}
break;
case 'Utopia\Validator\JSON':
case 'Utopia\Validator\Mock':
@@ -539,7 +542,7 @@ class Swagger2 extends Format
$node['items'] = [
'type' => 'string',
];
$node['x-example'] = '["' . Permission::read(Role::any()) . '"]';
$node['x-example'] = ($param['example'] ?? '') ?: '["' . Permission::read(Role::any()) . '"]';
break;
case 'Utopia\Database\Validator\Roles':
$node['type'] = $validator->getType();
@@ -547,40 +550,49 @@ class Swagger2 extends Format
$node['items'] = [
'type' => 'string',
];
$node['x-example'] = '["' . Role::any()->toString() . '"]';
$node['x-example'] = ($param['example'] ?? '') ?: '["' . Role::any()->toString() . '"]';
break;
case 'Appwrite\Auth\Validator\Password':
$node['type'] = $validator->getType();
$node['format'] = 'password';
$node['x-example'] = 'password';
$node['x-example'] = ($param['example'] ?? '') ?: 'password';
break;
case 'Appwrite\Auth\Validator\Phone':
$node['type'] = $validator->getType();
$node['format'] = 'phone';
$node['x-example'] = '+12065550100';
$node['x-example'] = ($param['example'] ?? '') ?: '+12065550100';
break;
case 'Utopia\Validator\Range':
/** @var Range $validator */
$node['type'] = $validator->getType() === Validator::TYPE_FLOAT ? 'number' : $validator->getType();
$node['format'] = $validator->getType() == Validator::TYPE_INTEGER ? 'int32' : 'float';
$node['x-example'] = $validator->getMin();
$node['x-example'] = ($param['example'] ?? '') ?: $validator->getMin();
break;
case 'Utopia\Validator\Integer':
$node['type'] = $validator->getType();
$node['format'] = 'int32';
if (!empty($param['example'])) {
$node['x-example'] = $param['example'];
}
break;
case 'Utopia\Validator\Numeric':
case 'Utopia\Validator\FloatValidator':
$node['type'] = 'number';
$node['format'] = 'float';
if (!empty($param['example'])) {
$node['x-example'] = $param['example'];
}
break;
case 'Utopia\Validator\Length':
$node['type'] = $validator->getType();
if (!empty($param['example'])) {
$node['x-example'] = $param['example'];
}
break;
case 'Utopia\Validator\WhiteList':
/** @var WhiteList $validator */
$node['type'] = $validator->getType();
$node['x-example'] = $validator->getList()[0];
$node['x-example'] = ($param['example'] ?? '') ?: $validator->getList()[0];
// Iterate the blackList. If it matches with the current one, then it is blackListed
$allowed = true;
@@ -601,7 +613,7 @@ class Swagger2 extends Format
break;
case 'Appwrite\Utopia\Database\Validator\CompoundUID':
$node['type'] = $validator->getType();
$node['x-example'] = '<ID1:ID2>';
$node['x-example'] = ($param['example'] ?? '') ?: '<ID1:ID2>';
break;
case 'Appwrite\Utopia\Database\Validator\Operation':
if ($array) {
@@ -618,22 +630,29 @@ class Swagger2 extends Format
} else {
$node['type'] = 'object';
}
$example = [
'action' => 'create',
'databaseId' => '<DATABASE_ID>',
$collectionIdKey => '<'.\strtoupper(Template::fromCamelCaseToSnake($collectionIdKey)).'>',
$documentIdKey => '<'.\strtoupper(Template::fromCamelCaseToSnake($documentIdKey)).'>',
'data' => [
'name' => 'Walter O\'Brien',
],
];
if ($array) {
$example = [$example];
if (empty($param['example'])) {
$example = [
'action' => 'create',
'databaseId' => '<DATABASE_ID>',
$collectionIdKey => '<'.\strtoupper(Template::fromCamelCaseToSnake($collectionIdKey)).'>',
$documentIdKey => '<'.\strtoupper(Template::fromCamelCaseToSnake($documentIdKey)).'>',
'data' => [
'name' => 'Walter O\'Brien',
],
];
if ($array) {
$example = [$example];
}
$node['x-example'] = \str_replace("\n", "\n\t", \json_encode($example, JSON_PRETTY_PRINT));
} else {
$node['x-example'] = $param['example'];
}
$node['x-example'] = \str_replace("\n", "\n\t", \json_encode($example, JSON_PRETTY_PRINT));
break;
default:
$node['type'] = 'string';
if (!empty($param['example'])) {
$node['x-example'] = $param['example'];
}
break;
}