From b667843a98ab3c9c01a89dfb55637ced0a95fcdd Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Sat, 22 Jun 2024 00:08:02 +0000 Subject: [PATCH] Add: NotificationController --- docs/controllers/NotificationController.yaml | 227 +++++++++++++++++++ docs/objects/Notification.yaml | 75 +++--- 2 files changed, 275 insertions(+), 27 deletions(-) create mode 100644 docs/controllers/NotificationController.yaml diff --git a/docs/controllers/NotificationController.yaml b/docs/controllers/NotificationController.yaml new file mode 100644 index 000000000..613e28e9e --- /dev/null +++ b/docs/controllers/NotificationController.yaml @@ -0,0 +1,227 @@ +components: + responses: + notification200: + description: Notification endpoint success. + content: + text/html: + schema: + type: string + example: OK + notification404: + description: An admin user is required or notification with the given ID not found. + content: + text/html: + schema: + type: string + example: Series not found. +paths: + /api/notifications: + get: + operationId: getNotifications + description: Get all Apprise notification events and notification settings for server. + tags: + - Notification + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + events: + type: array + items: + $ref: '../objects/Notification.yaml#/components/schemas/NotificationEvent' + settings: + $ref: '../objects/Notification.yaml#/components/schemas/NotificationSettings' + '404': + $ref: '#/components/responses/notification404' + patch: + operation: updateNotificationSettings + description: Update Notification settings. + tags: + - Notification + requestBody: + description: The Apprise Notification settings + content: + application/json: + schema: + properties: + appriseApiUrl: + $ref: '../objects/Notification.yaml#/components/schemas/appriseApiUrl' + maxFailedAttempts: + $ref: '../objects/Notification.yaml#/components/schemas/maxFailedAttempts' + maxNotificationQueue: + $ref: '../objects/Notification.yaml#/components/schemas/maxNotificationQueue' + responses: + '200': + $ref: '#/components/responses/notification200' + '404': + $ref: '#/components/responses/notification404' + post: + operation: createNotification + description: Update Notification settings. + tags: + - Notification + requestBody: + content: + application/json: + schema: + type: object + properties: + libraryId: + $ref: '../objects/Library.yaml#/components/schemas/libraryId' + eventName: + $ref: '../objects/Notification.yaml#/components/schemas/notificationEventName' + urls: + $ref: '../objects/Notification.yaml#/components/schemas/urls' + titleTemplate: + $ref: '../objects/Notification.yaml#/components/schemas/titleTemplate' + bodyTemplate: + $ref: '../objects/Notification.yaml#/components/schemas/bodyTemplate' + enabled: + $ref: '../objects/Notification.yaml#/components/schemas/enabled' + type: + $ref: '../objects/Notification.yaml#/components/schemas/notificationType' + required: + - eventName + - urls + - titleTemplate + - bodyTemplate + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + settings: + $ref: '../objects/Notification.yaml#/components/schemas/NotificationSettings' + '404': + $ref: '#/components/responses/notification404' + /api/notificationdata: + get: + operationId: getNotificationEventData + description: Get all Apprise notification event data for the server. + tags: + - Notification + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + events: + type: array + items: + $ref: '../objects/Notification.yaml#/components/schemas/NotificationEvent' + '404': + $ref: '#/components/responses/notification404' + /api/notifications/test: + get: + operationId: sendDefaultTestNotification + description: Send a test notification. + tags: + - Notification + parameters: + - in: query + name: fail + description: Whether to intentionally cause the notification to fail. `0` for false, `1` for true. + schema: + type: integer + responses: + '200': + $ref: '#/components/responses/notification200' + '404': + $ref: '#/components/responses/notification404' + /api/notifications/{id}: + parameters: + - name: id + in: path + description: The ID of the notification. + required: true + schema: + $ref: '../objects/Notification.yaml#/components/schemas/notificationId' + delete: + operationId: deleteNotification + description: Delete the notification by ID and return the notification settings. + tags: + - Notification + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + settings: + $ref: '../objects/Notification.yaml#/components/schemas/NotificationSettings' + '404': + $ref: '#/components/responses/notification404' + patch: + operation: createNotification + description: Update Notification settings. + tags: + - Notification + requestBody: + content: + application/json: + schema: + type: object + properties: + id: + $ref: '../objects/Notification.yaml#/components/schemas/notificationId' + libraryId: + $ref: '../objects/Library.yaml#/components/schemas/libraryId' + eventName: + $ref: '../objects/Notification.yaml#/components/schemas/notificationEventName' + urls: + $ref: '../objects/Notification.yaml#/components/schemas/urls' + titleTemplate: + $ref: '../objects/Notification.yaml#/components/schemas/titleTemplate' + bodyTemplate: + $ref: '../objects/Notification.yaml#/components/schemas/bodyTemplate' + enabled: + $ref: '../objects/Notification.yaml#/components/schemas/enabled' + type: + $ref: '../objects/Notification.yaml#/components/schemas/notificationType' + required: + - id + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + settings: + $ref: '../objects/Notification.yaml#/components/schemas/NotificationSettings' + '404': + $ref: '#/components/responses/notification404' + /api/notifications/{id}/test: + parameters: + - name: id + in: path + description: The ID of the notification. + required: true + schema: + $ref: '../objects/Notification.yaml#/components/schemas/notificationId' + get: + operationId: sendTestNotification + description: Send a test to the given notification. + tags: + - Notification + responses: + '200': + $ref: '#/components/responses/notification200' + '404': + $ref: '#/components/responses/notification404' diff --git a/docs/objects/Notification.yaml b/docs/objects/Notification.yaml index 859eda588..388970d7a 100644 --- a/docs/objects/Notification.yaml +++ b/docs/objects/Notification.yaml @@ -5,6 +5,45 @@ components: description: The ID of the notification. format: uuid example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + appriseApiUrl: + type: string + nullable: true + description: The full URL where the Apprise API to use is located. + maxFailedAttempts: + type: integer + minimum: 0 + default: 5 + description: The maximum number of times a notification fails before being disabled. + maxNotificationQueue: + type: integer + description: The maximum number of notifications in the notification queue before events are ignored. + notificationEventName: + type: string + description: The name of the event the notification will fire on. + enum: ['onPodcastEpisodeDownloaded', 'onTest'] + urls: + type: array + items: + type: string + description: The Apprise URLs to use for the notification. + example: http://192.168.0.3:8000/notify/my-cool-notification + titleTemplate: + type: string + description: The template for the notification title. + example: 'New {{podcastTitle}} Episode!' + bodyTemplate: + type: string + description: The template for the notification body. + example: '{{episodeTitle}} has been added to {{libraryName}} library.' + enabled: + type: boolean + default: false + description: Whether the notification is enabled. + notificationType: + type: string + enum: ['info', 'success', 'warning', 'failure'] + default: 'info' + description: The notification's type. Notification: type: object properties: @@ -13,31 +52,17 @@ components: libraryId: $ref: './Library.yaml#/components/schemas/libraryId' eventName: - type: string - description: The name of the event the notification will fire on. - enum: ['onPodcastEpisodeDownloaded', 'onTest'] + $ref: '#/components/schemas/notificationEventName' urls: - type: array - items: - type: string - description: The Apprise URLs to use for the notification. - example: http://192.168.0.3:8000/notify/my-cool-notification + $ref: '#/components/schemas/urls' titleTemplate: - type: string - description: The template for the notification title. - example: 'New {{podcastTitle}} Episode!' + $ref: '#/components/schemas/titleTemplate' bodyTemplate: - type: string - description: The template for the notification body. - example: '{{episodeTitle}} has been added to {{libraryName}} library.' + $ref: '#/components/schemas/bodyTemplate' enabled: - type: boolean - description: Whether the notification is enabled. + $ref: '#/components/schemas/enabled' type: - type: string - enum: ['info', 'success', 'warning', 'failure'] - default: 'info' - description: The notification's type. + $ref: '#/components/schemas/notificationType' lastFiredAt: type: integer nullable: true @@ -99,20 +124,16 @@ components: type: string description: The type of Apprise that will be used. At the moment, only api is available. appriseApiUrl: - type: string - nullable: true - description: The full URL where the Apprise API to use is located. + $ref: '#/components/schemas/appriseApiUrl' notifications: type: array items: $ref: '#/components/schemas/Notification' description: The set notifications. maxFailedAttempts: - type: integer - description: The maximum number of times a notification fails before being disabled. + $ref: '#/components/schemas/maxFailedAttempts' maxNotificationQueue: - type: integer - description: The maximum number of notifications in the notification queue before events are ignored. + $ref: '#/components/schemas/maxNotificationQueue' notificationDelay: type: integer description: The time (in ms) between notification pushes.