From 8f2a76ee7844e915650e389ad0346c80933d39be Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Sat, 28 Oct 2023 17:32:48 +0200 Subject: [PATCH 1/3] feat(api): Use OpenAPI scopes for push clients Signed-off-by: Joas Schilling --- lib/Controller/APIController.php | 2 + lib/Controller/PushController.php | 2 + lib/Controller/SettingsController.php | 3 + openapi-administration.json | 378 ++++++ openapi-full.json | 1556 +++++++++++++++++++++++++ openapi-push.json | 466 ++++++++ openapi.json | 784 +------------ 7 files changed, 2465 insertions(+), 726 deletions(-) create mode 100644 openapi-administration.json create mode 100644 openapi-full.json create mode 100644 openapi-push.json diff --git a/lib/Controller/APIController.php b/lib/Controller/APIController.php index 3e70ba42b..164285367 100644 --- a/lib/Controller/APIController.php +++ b/lib/Controller/APIController.php @@ -27,6 +27,7 @@ namespace OCA\Notifications\Controller; use OCP\AppFramework\Http; +use OCP\AppFramework\Http\Attribute\OpenAPI; use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\OCSController; use OCP\AppFramework\Utility\ITimeFactory; @@ -71,6 +72,7 @@ public function __construct( * 400: Generating notification is not possible * 404: User not found */ + #[OpenAPI(scope: OpenAPI::SCOPE_ADMINISTRATION)] public function generateNotification(string $userId, string $shortMessage, string $longMessage = ''): DataResponse { $user = $this->userManager->get($userId); diff --git a/lib/Controller/PushController.php b/lib/Controller/PushController.php index 0126af5f4..1129548ed 100644 --- a/lib/Controller/PushController.php +++ b/lib/Controller/PushController.php @@ -30,6 +30,7 @@ use OC\Security\IdentityProof\Manager; use OCA\Notifications\ResponseDefinitions; use OCP\AppFramework\Http; +use OCP\AppFramework\Http\Attribute\OpenAPI; use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\OCSController; use OCP\Authentication\Exceptions\InvalidTokenException; @@ -44,6 +45,7 @@ /** * @psalm-import-type NotificationsPushDevice from ResponseDefinitions */ +#[OpenAPI(scope: 'push')] class PushController extends OCSController { /** @var IDBConnection */ private $db; diff --git a/lib/Controller/SettingsController.php b/lib/Controller/SettingsController.php index 7c53b2a0f..36716c6cb 100644 --- a/lib/Controller/SettingsController.php +++ b/lib/Controller/SettingsController.php @@ -29,6 +29,7 @@ use OCA\Notifications\AppInfo\Application; use OCA\Notifications\Model\SettingsMapper; use OCP\AppFramework\Http; +use OCP\AppFramework\Http\Attribute\OpenAPI; use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\OCSController; use OCP\IConfig; @@ -62,6 +63,7 @@ public function __construct(string $appName, * * 200: Personal settings updated */ + #[OpenAPI] public function personal(int $batchSetting, string $soundNotification, string $soundTalk): DataResponse { $this->settingsMapper->setBatchSettingForUser($this->userId, $batchSetting); @@ -83,6 +85,7 @@ public function personal(int $batchSetting, string $soundNotification, string $s * * 200: Admin settings updated */ + #[OpenAPI(scope: OpenAPI::SCOPE_ADMINISTRATION)] public function admin(int $batchSetting, string $soundNotification, string $soundTalk): DataResponse { $this->config->setAppValue(Application::APP_ID, 'setting_batchtime', (string) $batchSetting); $this->config->setAppValue(Application::APP_ID, 'sound_notification', $soundNotification !== 'no' ? 'yes' : 'no'); diff --git a/openapi-administration.json b/openapi-administration.json new file mode 100644 index 000000000..35bc70203 --- /dev/null +++ b/openapi-administration.json @@ -0,0 +1,378 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "notifications-administration", + "version": "0.0.1", + "description": "This app provides a backend and frontend for the notification API available in Nextcloud.", + "license": { + "name": "agpl" + } + }, + "components": { + "securitySchemes": { + "basic_auth": { + "type": "http", + "scheme": "basic" + }, + "bearer_auth": { + "type": "http", + "scheme": "bearer" + } + }, + "schemas": { + "OCSMeta": { + "type": "object", + "required": [ + "status", + "statuscode" + ], + "properties": { + "status": { + "type": "string" + }, + "statuscode": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "totalitems": { + "type": "string" + }, + "itemsperpage": { + "type": "string" + } + } + }, + "Capabilities": { + "type": "object", + "required": [ + "notifications" + ], + "properties": { + "notifications": { + "type": "object", + "required": [ + "ocs-endpoints", + "push", + "admin-notifications" + ], + "properties": { + "ocs-endpoints": { + "type": "array", + "items": { + "type": "string" + } + }, + "push": { + "type": "array", + "items": { + "type": "string" + } + }, + "admin-notifications": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + }, + "paths": { + "/ocs/v2.php/apps/notifications/api/{apiVersion}/admin_notifications/{userId}": { + "post": { + "operationId": "api-generate-notification", + "summary": "Generate a notification for a user", + "description": "This endpoint requires admin access", + "tags": [ + "api" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "shortMessage", + "in": "query", + "description": "Subject of the notification", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "longMessage", + "in": "query", + "description": "Message of the notification", + "schema": { + "type": "string", + "default": "" + } + }, + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v1", + "v2" + ], + "default": "v2" + } + }, + { + "name": "userId", + "in": "path", + "description": "ID of the user", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Notification generated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "400": { + "description": "Generating notification is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + }, + "404": { + "description": "User not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + }, + "500": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/settings/admin": { + "post": { + "operationId": "settings-admin", + "summary": "Update default notification settings for new users", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "batchSetting", + "in": "query", + "description": "How often E-mails about missed notifications should be sent (hourly: 1; every three hours: 2; daily: 3; weekly: 4)", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "soundNotification", + "in": "query", + "description": "Enable sound for notifications ('yes' or 'no')", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "soundTalk", + "in": "query", + "description": "Enable sound for Talk notifications ('yes' or 'no')", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Admin settings updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + } + }, + "tags": [] +} \ No newline at end of file diff --git a/openapi-full.json b/openapi-full.json new file mode 100644 index 000000000..f3dd138df --- /dev/null +++ b/openapi-full.json @@ -0,0 +1,1556 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "notifications-full", + "version": "0.0.1", + "description": "This app provides a backend and frontend for the notification API available in Nextcloud.", + "license": { + "name": "agpl" + } + }, + "components": { + "securitySchemes": { + "basic_auth": { + "type": "http", + "scheme": "basic" + }, + "bearer_auth": { + "type": "http", + "scheme": "bearer" + } + }, + "schemas": { + "Capabilities": { + "type": "object", + "required": [ + "notifications" + ], + "properties": { + "notifications": { + "type": "object", + "required": [ + "ocs-endpoints", + "push", + "admin-notifications" + ], + "properties": { + "ocs-endpoints": { + "type": "array", + "items": { + "type": "string" + } + }, + "push": { + "type": "array", + "items": { + "type": "string" + } + }, + "admin-notifications": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + }, + "Notification": { + "type": "object", + "required": [ + "notification_id", + "app", + "user", + "datetime", + "object_type", + "object_id", + "subject", + "message", + "link", + "actions" + ], + "properties": { + "notification_id": { + "type": "integer", + "format": "int64" + }, + "app": { + "type": "string" + }, + "user": { + "type": "string" + }, + "datetime": { + "type": "string" + }, + "object_type": { + "type": "string" + }, + "object_id": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "message": { + "type": "string" + }, + "link": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NotificationAction" + } + }, + "subjectRich": { + "type": "string" + }, + "subjectRichParameters": { + "type": "object", + "additionalProperties": { + "type": "object" + } + }, + "messageRich": { + "type": "string" + }, + "messageRichParameters": { + "type": "object", + "additionalProperties": { + "type": "object" + } + }, + "icon": { + "type": "string" + }, + "shouldNotify": { + "type": "boolean" + } + } + }, + "NotificationAction": { + "type": "object", + "required": [ + "label", + "link", + "type", + "primary" + ], + "properties": { + "label": { + "type": "string" + }, + "link": { + "type": "string" + }, + "type": { + "type": "string" + }, + "primary": { + "type": "boolean" + } + } + }, + "OCSMeta": { + "type": "object", + "required": [ + "status", + "statuscode" + ], + "properties": { + "status": { + "type": "string" + }, + "statuscode": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "totalitems": { + "type": "string" + }, + "itemsperpage": { + "type": "string" + } + } + }, + "PushDevice": { + "type": "object", + "required": [ + "publicKey", + "deviceIdentifier", + "signature" + ], + "properties": { + "publicKey": { + "type": "string" + }, + "deviceIdentifier": { + "type": "string" + }, + "signature": { + "type": "string" + } + } + } + } + }, + "paths": { + "/ocs/v2.php/apps/notifications/api/{apiVersion}/notifications": { + "get": { + "operationId": "endpoint-list-notifications", + "summary": "Get all notifications", + "tags": [ + "endpoint" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "description": "Version of the API to use", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v1", + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Notifications returned", + "headers": { + "X-Nextcloud-User-Status": { + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Notification" + } + } + } + } + } + } + } + } + }, + "204": { + "description": "No app uses notifications", + "headers": { + "X-Nextcloud-User-Status": { + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + } + } + }, + "delete": { + "operationId": "endpoint-delete-all-notifications", + "summary": "Delete all notifications", + "tags": [ + "endpoint" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v1", + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "All notifications deleted successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Deleting notification for impersonated user is not allowed", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/notifications/{id}": { + "get": { + "operationId": "endpoint-get-notification", + "summary": "Get a notification", + "tags": [ + "endpoint" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "description": "Version of the API to use", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v1", + "v2" + ], + "default": "v2" + } + }, + { + "name": "id", + "in": "path", + "description": "ID of the notification", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Notification returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "$ref": "#/components/schemas/Notification" + } + } + } + } + } + } + } + }, + "404": { + "description": "Notification not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + } + } + }, + "delete": { + "operationId": "endpoint-delete-notification", + "summary": "Delete a notification", + "tags": [ + "endpoint" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v1", + "v2" + ], + "default": "v2" + } + }, + { + "name": "id", + "in": "path", + "description": "ID of the notification", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Notification deleted successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Deleting notification for impersonated user is not allowed", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + }, + "404": { + "description": "Notification not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/notifications/exists": { + "post": { + "operationId": "endpoint-confirm-ids-for-user", + "summary": "Check if notification IDs exist", + "tags": [ + "endpoint" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "ids[]", + "in": "query", + "description": "IDs of the notifications to check", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + } + } + }, + { + "name": "apiVersion", + "in": "path", + "description": "Version of the API to use", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v1", + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Existing notification IDs returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + } + } + } + } + } + } + } + } + }, + "400": { + "description": "Too many notification IDs requested", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + } + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/settings": { + "post": { + "operationId": "settings-personal", + "summary": "Update personal notification settings", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "batchSetting", + "in": "query", + "description": "How often E-mails about missed notifications should be sent (hourly: 1; every three hours: 2; daily: 3; weekly: 4)", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "soundNotification", + "in": "query", + "description": "Enable sound for notifications ('yes' or 'no')", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "soundTalk", + "in": "query", + "description": "Enable sound for Talk notifications ('yes' or 'no')", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Personal settings updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/push": { + "post": { + "operationId": "push-register-device", + "summary": "Register device for push notifications", + "tags": [ + "push" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "pushTokenHash", + "in": "query", + "description": "Hash of the push token", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "devicePublicKey", + "in": "query", + "description": "Public key of the device", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "proxyServer", + "in": "query", + "description": "Proxy server to be used", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Device was already registered", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "$ref": "#/components/schemas/PushDevice" + } + } + } + } + } + } + } + }, + "201": { + "description": "Device registered successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "$ref": "#/components/schemas/PushDevice" + } + } + } + } + } + } + } + }, + "400": { + "description": "Registering device is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "401": { + "description": "Missing permissions to register device", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + }, + "delete": { + "operationId": "push-remove-device", + "summary": "Remove a device from push notifications", + "tags": [ + "push" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "No device registered", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "202": { + "description": "Device removed successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Missing permissions to remove device", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "400": { + "description": "Removing device is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/admin_notifications/{userId}": { + "post": { + "operationId": "api-generate-notification", + "summary": "Generate a notification for a user", + "description": "This endpoint requires admin access", + "tags": [ + "api" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "shortMessage", + "in": "query", + "description": "Subject of the notification", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "longMessage", + "in": "query", + "description": "Message of the notification", + "schema": { + "type": "string", + "default": "" + } + }, + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v1", + "v2" + ], + "default": "v2" + } + }, + { + "name": "userId", + "in": "path", + "description": "ID of the user", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Notification generated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "400": { + "description": "Generating notification is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + }, + "404": { + "description": "User not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + }, + "500": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "nullable": true + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/notifications/api/{apiVersion}/settings/admin": { + "post": { + "operationId": "settings-admin", + "summary": "Update default notification settings for new users", + "description": "This endpoint requires admin access", + "tags": [ + "settings" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "batchSetting", + "in": "query", + "description": "How often E-mails about missed notifications should be sent (hourly: 1; every three hours: 2; daily: 3; weekly: 4)", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "soundNotification", + "in": "query", + "description": "Enable sound for notifications ('yes' or 'no')", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "soundTalk", + "in": "query", + "description": "Enable sound for Talk notifications ('yes' or 'no')", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Admin settings updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + } + }, + "tags": [] +} \ No newline at end of file diff --git a/openapi-push.json b/openapi-push.json new file mode 100644 index 000000000..c92478c4f --- /dev/null +++ b/openapi-push.json @@ -0,0 +1,466 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "notifications-push", + "version": "0.0.1", + "description": "This app provides a backend and frontend for the notification API available in Nextcloud.", + "license": { + "name": "agpl" + } + }, + "components": { + "securitySchemes": { + "basic_auth": { + "type": "http", + "scheme": "basic" + }, + "bearer_auth": { + "type": "http", + "scheme": "bearer" + } + }, + "schemas": { + "OCSMeta": { + "type": "object", + "required": [ + "status", + "statuscode" + ], + "properties": { + "status": { + "type": "string" + }, + "statuscode": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "totalitems": { + "type": "string" + }, + "itemsperpage": { + "type": "string" + } + } + }, + "PushDevice": { + "type": "object", + "required": [ + "publicKey", + "deviceIdentifier", + "signature" + ], + "properties": { + "publicKey": { + "type": "string" + }, + "deviceIdentifier": { + "type": "string" + }, + "signature": { + "type": "string" + } + } + }, + "Capabilities": { + "type": "object", + "required": [ + "notifications" + ], + "properties": { + "notifications": { + "type": "object", + "required": [ + "ocs-endpoints", + "push", + "admin-notifications" + ], + "properties": { + "ocs-endpoints": { + "type": "array", + "items": { + "type": "string" + } + }, + "push": { + "type": "array", + "items": { + "type": "string" + } + }, + "admin-notifications": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + }, + "paths": { + "/ocs/v2.php/apps/notifications/api/{apiVersion}/push": { + "post": { + "operationId": "push-register-device", + "summary": "Register device for push notifications", + "tags": [ + "push" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "pushTokenHash", + "in": "query", + "description": "Hash of the push token", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "devicePublicKey", + "in": "query", + "description": "Public key of the device", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "proxyServer", + "in": "query", + "description": "Proxy server to be used", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Device was already registered", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "$ref": "#/components/schemas/PushDevice" + } + } + } + } + } + } + } + }, + "201": { + "description": "Device registered successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "$ref": "#/components/schemas/PushDevice" + } + } + } + } + } + } + } + }, + "400": { + "description": "Registering device is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "401": { + "description": "Missing permissions to register device", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + }, + "delete": { + "operationId": "push-remove-device", + "summary": "Remove a device from push notifications", + "tags": [ + "push" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "apiVersion", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "v2" + ], + "default": "v2" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "No device registered", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "202": { + "description": "Device removed successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Missing permissions to remove device", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "400": { + "description": "Removing device is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + } + } + }, + "tags": [] +} \ No newline at end of file diff --git a/openapi.json b/openapi.json index 2ab0110e1..e147e9be3 100644 --- a/openapi.json +++ b/openapi.json @@ -20,39 +20,27 @@ } }, "schemas": { - "Capabilities": { + "OCSMeta": { "type": "object", "required": [ - "notifications" + "status", + "statuscode" ], "properties": { - "notifications": { - "type": "object", - "required": [ - "ocs-endpoints", - "push", - "admin-notifications" - ], - "properties": { - "ocs-endpoints": { - "type": "array", - "items": { - "type": "string" - } - }, - "push": { - "type": "array", - "items": { - "type": "string" - } - }, - "admin-notifications": { - "type": "array", - "items": { - "type": "string" - } - } - } + "status": { + "type": "string" + }, + "statuscode": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "totalitems": { + "type": "string" + }, + "itemsperpage": { + "type": "string" } } }, @@ -154,46 +142,39 @@ } } }, - "OCSMeta": { - "type": "object", - "required": [ - "status", - "statuscode" - ], - "properties": { - "status": { - "type": "string" - }, - "statuscode": { - "type": "integer" - }, - "message": { - "type": "string" - }, - "totalitems": { - "type": "string" - }, - "itemsperpage": { - "type": "string" - } - } - }, - "PushDevice": { + "Capabilities": { "type": "object", "required": [ - "publicKey", - "deviceIdentifier", - "signature" + "notifications" ], "properties": { - "publicKey": { - "type": "string" - }, - "deviceIdentifier": { - "type": "string" - }, - "signature": { - "type": "string" + "notifications": { + "type": "object", + "required": [ + "ocs-endpoints", + "push", + "admin-notifications" + ], + "properties": { + "ocs-endpoints": { + "type": "array", + "items": { + "type": "string" + } + }, + "push": { + "type": "array", + "items": { + "type": "string" + } + }, + "admin-notifications": { + "type": "array", + "items": { + "type": "string" + } + } + } } } } @@ -803,12 +784,12 @@ } } }, - "/ocs/v2.php/apps/notifications/api/{apiVersion}/push": { + "/ocs/v2.php/apps/notifications/api/{apiVersion}/settings": { "post": { - "operationId": "push-register-device", - "summary": "Register device for push notifications", + "operationId": "settings-personal", + "summary": "Update personal notification settings", "tags": [ - "push" + "settings" ], "security": [ { @@ -820,577 +801,28 @@ ], "parameters": [ { - "name": "pushTokenHash", + "name": "batchSetting", "in": "query", - "description": "Hash of the push token", + "description": "How often E-mails about missed notifications should be sent (hourly: 1; every three hours: 2; daily: 3; weekly: 4)", "required": true, "schema": { - "type": "string" + "type": "integer", + "format": "int64" } }, { - "name": "devicePublicKey", + "name": "soundNotification", "in": "query", - "description": "Public key of the device", + "description": "Enable sound for notifications ('yes' or 'no')", "required": true, "schema": { "type": "string" } }, { - "name": "proxyServer", + "name": "soundTalk", "in": "query", - "description": "Proxy server to be used", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "apiVersion", - "in": "path", - "required": true, - "schema": { - "type": "string", - "enum": [ - "v2" - ], - "default": "v2" - } - }, - { - "name": "OCS-APIRequest", - "in": "header", - "description": "Required to be true for the API request to pass", - "required": true, - "schema": { - "type": "boolean", - "default": true - } - } - ], - "responses": { - "200": { - "description": "Device was already registered", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": { - "$ref": "#/components/schemas/PushDevice" - } - } - } - } - } - } - } - }, - "201": { - "description": "Device registered successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": { - "$ref": "#/components/schemas/PushDevice" - } - } - } - } - } - } - } - }, - "400": { - "description": "Registering device is not possible", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": { - "type": "object", - "required": [ - "message" - ], - "properties": { - "message": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "401": { - "description": "Missing permissions to register device", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": {} - } - } - } - } - } - } - } - } - }, - "delete": { - "operationId": "push-remove-device", - "summary": "Remove a device from push notifications", - "tags": [ - "push" - ], - "security": [ - { - "bearer_auth": [] - }, - { - "basic_auth": [] - } - ], - "parameters": [ - { - "name": "apiVersion", - "in": "path", - "required": true, - "schema": { - "type": "string", - "enum": [ - "v2" - ], - "default": "v2" - } - }, - { - "name": "OCS-APIRequest", - "in": "header", - "description": "Required to be true for the API request to pass", - "required": true, - "schema": { - "type": "boolean", - "default": true - } - } - ], - "responses": { - "200": { - "description": "No device registered", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": {} - } - } - } - } - } - } - }, - "202": { - "description": "Device removed successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": {} - } - } - } - } - } - } - }, - "401": { - "description": "Missing permissions to remove device", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": {} - } - } - } - } - } - } - }, - "400": { - "description": "Removing device is not possible", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": { - "type": "object", - "required": [ - "message" - ], - "properties": { - "message": { - "type": "string" - } - } - } - } - } - } - } - } - } - } - } - } - }, - "/ocs/v2.php/apps/notifications/api/{apiVersion}/admin_notifications/{userId}": { - "post": { - "operationId": "api-generate-notification", - "summary": "Generate a notification for a user", - "description": "This endpoint requires admin access", - "tags": [ - "api" - ], - "security": [ - { - "bearer_auth": [] - }, - { - "basic_auth": [] - } - ], - "parameters": [ - { - "name": "shortMessage", - "in": "query", - "description": "Subject of the notification", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "longMessage", - "in": "query", - "description": "Message of the notification", - "schema": { - "type": "string", - "default": "" - } - }, - { - "name": "apiVersion", - "in": "path", - "required": true, - "schema": { - "type": "string", - "enum": [ - "v1", - "v2" - ], - "default": "v2" - } - }, - { - "name": "userId", - "in": "path", - "description": "ID of the user", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "OCS-APIRequest", - "in": "header", - "description": "Required to be true for the API request to pass", - "required": true, - "schema": { - "type": "boolean", - "default": true - } - } - ], - "responses": { - "200": { - "description": "Notification generated successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": {} - } - } - } - } - } - } - }, - "400": { - "description": "Generating notification is not possible", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": { - "nullable": true - } - } - } - } - } - } - } - }, - "404": { - "description": "User not found", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": { - "nullable": true - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": { - "nullable": true - } - } - } - } - } - } - } - } - } - } - }, - "/ocs/v2.php/apps/notifications/api/{apiVersion}/settings": { - "post": { - "operationId": "settings-personal", - "summary": "Update personal notification settings", - "tags": [ - "settings" - ], - "security": [ - { - "bearer_auth": [] - }, - { - "basic_auth": [] - } - ], - "parameters": [ - { - "name": "batchSetting", - "in": "query", - "description": "How often E-mails about missed notifications should be sent (hourly: 1; every three hours: 2; daily: 3; weekly: 4)", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - }, - { - "name": "soundNotification", - "in": "query", - "description": "Enable sound for notifications ('yes' or 'no')", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "soundTalk", - "in": "query", - "description": "Enable sound for Talk notifications ('yes' or 'no')", + "description": "Enable sound for Talk notifications ('yes' or 'no')", "required": true, "schema": { "type": "string" @@ -1450,106 +882,6 @@ } } } - }, - "/ocs/v2.php/apps/notifications/api/{apiVersion}/settings/admin": { - "post": { - "operationId": "settings-admin", - "summary": "Update default notification settings for new users", - "description": "This endpoint requires admin access", - "tags": [ - "settings" - ], - "security": [ - { - "bearer_auth": [] - }, - { - "basic_auth": [] - } - ], - "parameters": [ - { - "name": "batchSetting", - "in": "query", - "description": "How often E-mails about missed notifications should be sent (hourly: 1; every three hours: 2; daily: 3; weekly: 4)", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - }, - { - "name": "soundNotification", - "in": "query", - "description": "Enable sound for notifications ('yes' or 'no')", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "soundTalk", - "in": "query", - "description": "Enable sound for Talk notifications ('yes' or 'no')", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "apiVersion", - "in": "path", - "required": true, - "schema": { - "type": "string", - "enum": [ - "v2" - ], - "default": "v2" - } - }, - { - "name": "OCS-APIRequest", - "in": "header", - "description": "Required to be true for the API request to pass", - "required": true, - "schema": { - "type": "boolean", - "default": true - } - } - ], - "responses": { - "200": { - "description": "Admin settings updated", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "ocs" - ], - "properties": { - "ocs": { - "type": "object", - "required": [ - "meta", - "data" - ], - "properties": { - "meta": { - "$ref": "#/components/schemas/OCSMeta" - }, - "data": {} - } - } - } - } - } - } - } - } - } } }, "tags": [] From 35909f158f8e24a6375614ca8d0e1ca36629a183 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Wed, 24 Jan 2024 10:22:51 +0100 Subject: [PATCH 2/3] chore(deps): Bump openapi-extractor Signed-off-by: Joas Schilling --- vendor-bin/openapi-extractor/composer.lock | 25 ++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/vendor-bin/openapi-extractor/composer.lock b/vendor-bin/openapi-extractor/composer.lock index 6424f4eee..759781689 100644 --- a/vendor-bin/openapi-extractor/composer.lock +++ b/vendor-bin/openapi-extractor/composer.lock @@ -82,12 +82,12 @@ "source": { "type": "git", "url": "https://github.com/nextcloud/openapi-extractor.git", - "reference": "aef9a921bebdcdc42b110a51bfb1e2ca281c307a" + "reference": "3b7b6ff9659a5f15612d4749e085bbcb83509049" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/nextcloud/openapi-extractor/zipball/aef9a921bebdcdc42b110a51bfb1e2ca281c307a", - "reference": "aef9a921bebdcdc42b110a51bfb1e2ca281c307a", + "url": "https://api.github.com/repos/nextcloud/openapi-extractor/zipball/3b7b6ff9659a5f15612d4749e085bbcb83509049", + "reference": "3b7b6ff9659a5f15612d4749e085bbcb83509049", "shasum": "" }, "require": { @@ -97,6 +97,9 @@ "php": "^8.1", "phpstan/phpdoc-parser": "^1.23" }, + "require-dev": { + "nextcloud/coding-standard": "^1.1" + }, "default-branch": true, "bin": [ "generate-spec", @@ -108,11 +111,25 @@ "OpenAPIExtractor\\": "src" } }, + "scripts": { + "lint": [ + "find . -name \\*.php -not -path './tests/*' -not -path './vendor/*' -not -path './build/*' -print0 | xargs -0 -n1 php -l && php -l generate-spec && php -l merge-specs" + ], + "cs:check": [ + "php-cs-fixer fix --dry-run --diff" + ], + "cs:fix": [ + "php-cs-fixer fix" + ], + "test:unit": [ + "cd tests && ../generate-spec" + ] + }, "support": { "source": "https://github.com/nextcloud/openapi-extractor/tree/main", "issues": "https://github.com/nextcloud/openapi-extractor/issues" }, - "time": "2023-10-06T05:18:46+00:00" + "time": "2024-01-18T14:53:21+00:00" }, { "name": "nikic/php-parser", From 9a345d8bc5c5d7dcf2adf98c0cf568489995a7ea Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Wed, 24 Jan 2024 10:24:40 +0100 Subject: [PATCH 3/3] chore(api): Regenerate OpenAPI docs Signed-off-by: Joas Schilling --- openapi-administration.json | 48 +++++++++---------- openapi-push.json | 72 ++++++++++++++--------------- openapi.json | 92 ++++++++++++++++++------------------- 3 files changed, 106 insertions(+), 106 deletions(-) diff --git a/openapi-administration.json b/openapi-administration.json index 35bc70203..437bbc1a6 100644 --- a/openapi-administration.json +++ b/openapi-administration.json @@ -20,30 +20,6 @@ } }, "schemas": { - "OCSMeta": { - "type": "object", - "required": [ - "status", - "statuscode" - ], - "properties": { - "status": { - "type": "string" - }, - "statuscode": { - "type": "integer" - }, - "message": { - "type": "string" - }, - "totalitems": { - "type": "string" - }, - "itemsperpage": { - "type": "string" - } - } - }, "Capabilities": { "type": "object", "required": [ @@ -79,6 +55,30 @@ } } } + }, + "OCSMeta": { + "type": "object", + "required": [ + "status", + "statuscode" + ], + "properties": { + "status": { + "type": "string" + }, + "statuscode": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "totalitems": { + "type": "string" + }, + "itemsperpage": { + "type": "string" + } + } } } }, diff --git a/openapi-push.json b/openapi-push.json index c92478c4f..a5f555bdd 100644 --- a/openapi-push.json +++ b/openapi-push.json @@ -20,6 +20,42 @@ } }, "schemas": { + "Capabilities": { + "type": "object", + "required": [ + "notifications" + ], + "properties": { + "notifications": { + "type": "object", + "required": [ + "ocs-endpoints", + "push", + "admin-notifications" + ], + "properties": { + "ocs-endpoints": { + "type": "array", + "items": { + "type": "string" + } + }, + "push": { + "type": "array", + "items": { + "type": "string" + } + }, + "admin-notifications": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + }, "OCSMeta": { "type": "object", "required": [ @@ -62,42 +98,6 @@ "type": "string" } } - }, - "Capabilities": { - "type": "object", - "required": [ - "notifications" - ], - "properties": { - "notifications": { - "type": "object", - "required": [ - "ocs-endpoints", - "push", - "admin-notifications" - ], - "properties": { - "ocs-endpoints": { - "type": "array", - "items": { - "type": "string" - } - }, - "push": { - "type": "array", - "items": { - "type": "string" - } - }, - "admin-notifications": { - "type": "array", - "items": { - "type": "string" - } - } - } - } - } } } }, diff --git a/openapi.json b/openapi.json index e147e9be3..7c668d915 100644 --- a/openapi.json +++ b/openapi.json @@ -20,27 +20,39 @@ } }, "schemas": { - "OCSMeta": { + "Capabilities": { "type": "object", "required": [ - "status", - "statuscode" + "notifications" ], "properties": { - "status": { - "type": "string" - }, - "statuscode": { - "type": "integer" - }, - "message": { - "type": "string" - }, - "totalitems": { - "type": "string" - }, - "itemsperpage": { - "type": "string" + "notifications": { + "type": "object", + "required": [ + "ocs-endpoints", + "push", + "admin-notifications" + ], + "properties": { + "ocs-endpoints": { + "type": "array", + "items": { + "type": "string" + } + }, + "push": { + "type": "array", + "items": { + "type": "string" + } + }, + "admin-notifications": { + "type": "array", + "items": { + "type": "string" + } + } + } } } }, @@ -142,39 +154,27 @@ } } }, - "Capabilities": { + "OCSMeta": { "type": "object", "required": [ - "notifications" + "status", + "statuscode" ], "properties": { - "notifications": { - "type": "object", - "required": [ - "ocs-endpoints", - "push", - "admin-notifications" - ], - "properties": { - "ocs-endpoints": { - "type": "array", - "items": { - "type": "string" - } - }, - "push": { - "type": "array", - "items": { - "type": "string" - } - }, - "admin-notifications": { - "type": "array", - "items": { - "type": "string" - } - } - } + "status": { + "type": "string" + }, + "statuscode": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "totalitems": { + "type": "string" + }, + "itemsperpage": { + "type": "string" } } }