From 4d7175d02cd3c76abb4c7938dce8c9711c85a670 Mon Sep 17 00:00:00 2001 From: Jacob Ransom Date: Tue, 5 Aug 2025 14:28:53 +1200 Subject: [PATCH 1/3] Initial attempt at adding Swagger annotations --- API.php | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) diff --git a/API.php b/API.php index 562e178a..5ee67135 100755 --- a/API.php +++ b/API.php @@ -17,6 +17,43 @@ /** * * @method static \Piwik\Plugins\CustomAlerts\API getInstance() + * + * @OA\Schema( + * schema="alert", + * title="Alert", + * type="object", + * @OA\Property( + * property="idAlert", + * description="ID of the alert", + * type="integer", + * ), + * @OA\Property( + * property="name", + * description="Name of the alert", + * type="string", + * ), + * @OA\Property( + * property="login", + * description="Name of the login or username to which the alert belongs", + * type="string", + * ), + * @OA\Property( + * property="period", + * description="Name of the period such as day, week, or month", + * type="string", + * ), + * @OA\Property( + * property="report", + * description="Name of the report which the alert monitors", + * type="string", + * ), + * @OA\Property( + * property="idSites", + * description="IDs of the sites", + * type="array", + * @OA\Items(type="integer") + * ) + * ) */ class API extends \Piwik\Plugin\API { @@ -41,6 +78,59 @@ public function __construct(Processor $processor, Validator $validator) * @param int $subPeriodN * * @return array + * + * @OA\Get( + * path="/index.php?method=CustomAlerts.getValuesForAlertInPast", + * operationId="CustomAlerts.getValuesForAlertInPast", + * tags={"CustomAlerts"}, + * @OA\Parameter(ref="#/components/parameters/module"), + * @OA\Parameter(ref="#/components/parameters/format"), + * @OA\Parameter( + * name="idAlert", + * in="query", + * description="The ID of the alert", + * required=true, + * @OA\Schema( + * type="integer" + * ) + * ), + * @OA\Parameter( + * name="subPeriodN", + * in="query", + * description="The number to subtract from the current (0) period", + * required=true, + * @OA\Schema( + * type="integer" + * ) + * ), + * @OA\Response( + * response="200", + * description="The collection of sites their the matching result for the specified period", + * @OA\JsonContent( + * type="array", + * @OA\Items( + * type="object", + * @OA\Property( + * property="idSite", + * description="ID of the site", + * type="integer", + * ), + * @OA\Property( + * property="value", + * description="Value of the alert for specific site", + * type="array", + * @OA\Items( + * oneOf={ + * @OA\Schema(type="string"), + * @OA\Schema(type="integer"), + * @OA\Schema(type="object") + * } + * ) + * ) + * ) + * ) + * ) + * ) */ public function getValuesForAlertInPast($idAlert, $subPeriodN) { @@ -64,6 +154,28 @@ public function getValuesForAlertInPast($idAlert, $subPeriodN) * * @return array * @throws \Exception In case alert does not exist or user has no permission to access alert. + * + * @OA\Get( + * path="/index.php?method=CustomAlerts.getAlert", + * operationId="CustomAlerts.getAlert", + * tags={"CustomAlerts"}, + * @OA\Parameter(ref="#/components/parameters/module"), + * @OA\Parameter(ref="#/components/parameters/format"), + * @OA\Parameter( + * name="idAlert", + * in="query", + * description="The ID of the alert", + * required=true, + * @OA\Schema( + * type="integer" + * ) + * ), + * @OA\Response( + * response="200", + * description="The properties of the requested alert", + * @OA\JsonContent(ref="#/components/schemas/alert") + * ) + * ) */ public function getAlert($idAlert) { @@ -90,6 +202,32 @@ private function getModel() * @param bool $ifSuperUserReturnAllAlerts * * @return array + * + * @OA\Get( + * path="/index.php?method=CustomAlerts.getAlerts", + * operationId="CustomAlerts.getAlerts", + * tags={"CustomAlerts"}, + * @OA\Parameter(ref="#/components/parameters/module"), + * @OA\Parameter(ref="#/components/parameters/format"), + * @OA\Parameter( + * name="idSites", + * in="query", + * description="The IDs of the sites to filter alerts by", + * required=true, + * @OA\Schema( + * type="array", + * @OA\Items(type="integer") + * ) + * ), + * @OA\Response( + * response="200", + * description="A collection of alerts matching the sites", + * @OA\JsonContent( + * type="array", + * @OA\Items(ref="#/components/schemas/alert") + * ) + * ) + * ) */ public function getAlerts($idSites, $ifSuperUserReturnAllAlerts = false) { From 4cc60fd933c4aa48f195018bc3e5eeab987c4c00 Mon Sep 17 00:00:00 2001 From: Jacob Ransom Date: Tue, 5 Aug 2025 17:51:27 +1200 Subject: [PATCH 2/3] Annotating enough to provide at least the majority of data --- API.php | 388 +++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 314 insertions(+), 74 deletions(-) diff --git a/API.php b/API.php index 5ee67135..65eedfdd 100755 --- a/API.php +++ b/API.php @@ -10,6 +10,7 @@ namespace Piwik\Plugins\CustomAlerts; use Exception; +use OpenApi\Annotations as OA; use Piwik\Common; use Piwik\Piwik; use Piwik\Site; @@ -19,41 +20,205 @@ * @method static \Piwik\Plugins\CustomAlerts\API getInstance() * * @OA\Schema( - * schema="alert", - * title="Alert", - * type="object", - * @OA\Property( - * property="idAlert", - * description="ID of the alert", - * type="integer", - * ), - * @OA\Property( - * property="name", - * description="Name of the alert", - * type="string", - * ), - * @OA\Property( - * property="login", - * description="Name of the login or username to which the alert belongs", - * type="string", - * ), - * @OA\Property( - * property="period", - * description="Name of the period such as day, week, or month", - * type="string", - * ), - * @OA\Property( - * property="report", - * description="Name of the report which the alert monitors", - * type="string", - * ), - * @OA\Property( - * property="idSites", - * description="IDs of the sites", - * type="array", - * @OA\Items(type="integer") - * ) - * ) + * schema="alert", + * title="Alert", + * type="object", + * @OA\Property( + * property="idAlert", + * description="ID of the alert", + * type="integer", + * ), + * @OA\Property( + * property="name", + * description="Name of the alert", + * type="string", + * ), + * @OA\Property( + * property="login", + * description="Name of the login of the user which created the alert", + * type="string", + * ), + * @OA\Property( + * property="period", + * description="Name of the period such as day, week, or month", + * type="string", + * ), + * @OA\Property( + * property="report", + * description="Name of the report which the alert monitors", + * type="string", + * ), + * @OA\Property( + * property="report_condition", + * type="string", + * ), + * @OA\Property( + * property="report_matched", + * type="string", + * ), + * @OA\Property( + * property="metric", + * type="string", + * ), + * @OA\Property( + * property="metric_condition", + * type="string", + * ), + * @OA\Property( + * property="metric_matched", + * type="number", + * ), + * @OA\Property( + * property="compared_to", + * type="integer", + * ), + * @OA\Property( + * property="email_me", + * type="boolean", + * enum={0,1} + * ), + * @OA\Property( + * property="additional_emails", + * type="array", + * @OA\Items(type="string") + * ), + * @OA\Property( + * property="phone_numbers", + * type="array", + * @OA\Items(type="string") + * ), + * @OA\Property( + * property="idSites", + * description="IDs of the sites", + * type="array", + * @OA\Items(type="integer") + * ) + * ) + * + * @OA\Parameter( + * parameter="idAlert", + * name="idAlert", + * in="query", + * description="The ID of the alert", + * required=true, + * @OA\Schema( + * type="integer" + * ) + * ) + * @OA\Parameter( + * parameter="alertName", + * name="name", + * in="query", + * description="The name to identify alert", + * required=true, + * @OA\Schema(type="string") + * ) + * @OA\Parameter( + * parameter="alertIdSites", + * name="idSites", + * in="query", + * description="The IDs of the sites for which an alert is configured", + * required=true, + * @OA\Schema( + * oneOf={ + * @OA\Schema(type="string"), + * @OA\Schema( + * type="array", + * @OA\Items( + * oneOf={ + * @OA\Schema(type="integer"), + * @OA\Schema(type="string") + * } + * ) + * ) + * } + * ) + * ) + * @OA\Parameter( + * parameter="alertPeriod", + * name="period", + * in="query", + * required=true, + * @OA\Schema(type="string") + * ) + * @OA\Parameter( + * parameter="alertEmailMe", + * name="emailMe", + * in="query", + * required=true, + * @OA\Schema(type="boolean") + * ) + * @OA\Parameter( + * parameter="alertAdditionalEmails", + * name="additionalEmails", + * in="query", + * required=true, + * @OA\Schema( + * type="array", + * minItems=0, + * @OA\Items(type="string") + * ) + * ) + * @OA\Parameter( + * parameter="alertPhoneNumbers", + * name="phoneNumbers", + * in="query", + * required=true, + * @OA\Schema( + * type="array", + * minItems=0, + * @OA\Items(type="string") + * ) + * ) + * @OA\Parameter( + * parameter="alertMetric", + * name="metric", + * in="query", + * required=true, + * @OA\Schema(type="string") + * ) + * @OA\Parameter( + * parameter="alertMetricCondition", + * name="metricCondition", + * in="query", + * required=true, + * @OA\Schema(type="string") + * ) + * @OA\Parameter( + * parameter="alertMetricValue", + * name="metricValue", + * in="query", + * required=true, + * @OA\Schema(type="number") + * ) + * @OA\Parameter( + * parameter="alertComparedTo", + * name="comparedTo", + * in="query", + * required=true, + * @OA\Schema(type="integer") + * ) + * @OA\Parameter( + * parameter="alertReportUniqueId", + * name="reportUniqueId", + * in="query", + * required=true, + * @OA\Schema(type="string") + * ) + * @OA\Parameter( + * parameter="alertReportCondition", + * name="reportCondition", + * in="query", + * required=false, + * @OA\Schema(type="string") + * ) + * @OA\Parameter( + * parameter="alertReportValue", + * name="reportValue", + * in="query", + * required=false, + * @OA\Schema(type="string") + * ) */ class API extends \Piwik\Plugin\API { @@ -85,15 +250,7 @@ public function __construct(Processor $processor, Validator $validator) * tags={"CustomAlerts"}, * @OA\Parameter(ref="#/components/parameters/module"), * @OA\Parameter(ref="#/components/parameters/format"), - * @OA\Parameter( - * name="idAlert", - * in="query", - * description="The ID of the alert", - * required=true, - * @OA\Schema( - * type="integer" - * ) - * ), + * @OA\Parameter(ref="#/components/parameters/idAlert"), * @OA\Parameter( * name="subPeriodN", * in="query", @@ -156,26 +313,18 @@ public function getValuesForAlertInPast($idAlert, $subPeriodN) * @throws \Exception In case alert does not exist or user has no permission to access alert. * * @OA\Get( - * path="/index.php?method=CustomAlerts.getAlert", - * operationId="CustomAlerts.getAlert", - * tags={"CustomAlerts"}, - * @OA\Parameter(ref="#/components/parameters/module"), - * @OA\Parameter(ref="#/components/parameters/format"), - * @OA\Parameter( - * name="idAlert", - * in="query", - * description="The ID of the alert", - * required=true, - * @OA\Schema( - * type="integer" - * ) - * ), - * @OA\Response( - * response="200", - * description="The properties of the requested alert", - * @OA\JsonContent(ref="#/components/schemas/alert") - * ) - * ) + * path="/index.php?method=CustomAlerts.getAlert", + * operationId="CustomAlerts.getAlert", + * tags={"CustomAlerts"}, + * @OA\Parameter(ref="#/components/parameters/module"), + * @OA\Parameter(ref="#/components/parameters/format"), + * @OA\Parameter(ref="#/components/parameters/idAlert"), + * @OA\Response( + * response="200", + * description="The properties of the requested alert", + * @OA\JsonContent(ref="#/components/schemas/alert") + * ) + * ) */ public function getAlert($idAlert) { @@ -209,16 +358,7 @@ private function getModel() * tags={"CustomAlerts"}, * @OA\Parameter(ref="#/components/parameters/module"), * @OA\Parameter(ref="#/components/parameters/format"), - * @OA\Parameter( - * name="idSites", - * in="query", - * description="The IDs of the sites to filter alerts by", - * required=true, - * @OA\Schema( - * type="array", - * @OA\Items(type="integer") - * ) - * ), + * @OA\Parameter(ref="#/components/parameters/alertIdSites"), * @OA\Response( * response="200", * description="A collection of alerts matching the sites", @@ -267,6 +407,32 @@ public function getAlerts($idSites, $ifSuperUserReturnAllAlerts = false) * @param bool|string $reportCondition * @param bool|string $reportValue * @return int ID of new Alert + * + * @OA\Post( + * path="/index.php?method=CustomAlerts.addAlert", + * operationId="CustomAlerts.addAlert", + * tags={"CustomAlerts"}, + * @OA\Parameter(ref="#/components/parameters/module"), + * @OA\Parameter(ref="#/components/parameters/format"), + * @OA\Parameter(ref="#/components/parameters/alertName"), + * @OA\Parameter(ref="#/components/parameters/alertIdSites"), + * @OA\Parameter(ref="#/components/parameters/alertPeriod"), + * @OA\Parameter(ref="#/components/parameters/alertEmailMe"), + * @OA\Parameter(ref="#/components/parameters/alertAdditionalEmails"), + * @OA\Parameter(ref="#/components/parameters/alertPhoneNumbers"), + * @OA\Parameter(ref="#/components/parameters/alertMetric"), + * @OA\Parameter(ref="#/components/parameters/alertMetricCondition"), + * @OA\Parameter(ref="#/components/parameters/alertMetricValue"), + * @OA\Parameter(ref="#/components/parameters/alertComparedTo"), + * @OA\Parameter(ref="#/components/parameters/alertReportUniqueId"), + * @OA\Parameter(ref="#/components/parameters/alertReportCondition"), + * @OA\Parameter(ref="#/components/parameters/alertReportValue"), + * @OA\Response( + * response="200", + * description="ID of the newly created alert", + * @OA\JsonContent(type="integer") + * ) + * ) */ public function addAlert($name, $idSites, $period, $emailMe, $additionalEmails, $phoneNumbers, $metric, $metricCondition, $metricValue, $comparedTo, $reportUniqueId, $reportCondition = false, $reportValue = false) { @@ -356,6 +522,33 @@ private function checkAlert($idSites, $name, $period, $additionalEmails, $metric * @param bool|string $reportValue * * @return boolean + * + * @OA\Post( + * path="/index.php?method=CustomAlerts.editAlert", + * operationId="CustomAlerts.editAlert", + * tags={"CustomAlerts"}, + * @OA\Parameter(ref="#/components/parameters/module"), + * @OA\Parameter(ref="#/components/parameters/format"), + * @OA\Parameter(ref="#/components/parameters/idAlert"), + * @OA\Parameter(ref="#/components/parameters/alertName"), + * @OA\Parameter(ref="#/components/parameters/alertIdSites"), + * @OA\Parameter(ref="#/components/parameters/alertPeriod"), + * @OA\Parameter(ref="#/components/parameters/alertEmailMe"), + * @OA\Parameter(ref="#/components/parameters/alertAdditionalEmails"), + * @OA\Parameter(ref="#/components/parameters/alertPhoneNumbers"), + * @OA\Parameter(ref="#/components/parameters/alertMetric"), + * @OA\Parameter(ref="#/components/parameters/alertMetricCondition"), + * @OA\Parameter(ref="#/components/parameters/alertMetricValue"), + * @OA\Parameter(ref="#/components/parameters/alertComparedTo"), + * @OA\Parameter(ref="#/components/parameters/alertReportUniqueId"), + * @OA\Parameter(ref="#/components/parameters/alertReportCondition"), + * @OA\Parameter(ref="#/components/parameters/alertReportValue"), + * @OA\Response( + * response="200", + * description="Boolean indicating success", + * @OA\JsonContent(type="boolean") + * ) + * ) */ public function editAlert($idAlert, $name, $idSites, $period, $emailMe, $additionalEmails, $phoneNumbers, $metric, $metricCondition, $metricValue, $comparedTo, $reportUniqueId, $reportCondition = false, $reportValue = false) { @@ -385,6 +578,27 @@ public function editAlert($idAlert, $name, $idSites, $period, $emailMe, $additio * * @param int $idAlert * @throws \Exception + * + * @OA\Delete( + * path="/index.php?method=CustomAlerts.deleteAlert", + * operationId="CustomAlerts.deleteAlert", + * tags={"CustomAlerts"}, + * @OA\Parameter(ref="#/components/parameters/module"), + * @OA\Parameter(ref="#/components/parameters/format"), + * @OA\Parameter( + * name="idAlert", + * in="query", + * description="The ID of the alert", + * required=true, + * @OA\Schema( + * type="integer" + * ) + * ), + * @OA\Response( + * response="200", + * description="200 response without body" + * ) + * ) */ public function deleteAlert($idAlert) { @@ -400,6 +614,32 @@ public function deleteAlert($idAlert) * @param int[] idSites * * @return array + * + * @OA\Get( + * path="/index.php?method=CustomAlerts.getTriggeredAlerts", + * operationId="CustomAlerts.getTriggeredAlerts", + * tags={"CustomAlerts"}, + * @OA\Parameter(ref="#/components/parameters/module"), + * @OA\Parameter(ref="#/components/parameters/format"), + * @OA\Parameter( + * name="idSites", + * in="query", + * description="The IDs of the sites to filter alerts by", + * required=true, + * @OA\Schema( + * type="array", + * @OA\Items(type="integer") + * ) + * ), + * @OA\Response( + * response="200", + * description="A collection of alerts matching the sites", + * @OA\JsonContent( + * type="array", + * @OA\Items(ref="#/components/schemas/alert") + * ) + * ) + * ) */ public function getTriggeredAlerts($idSites) { From 9e7707409e849da02d716f79ceff1cdbc2a838a4 Mon Sep 17 00:00:00 2001 From: Jacob Ransom Date: Tue, 5 Aug 2025 17:57:43 +1200 Subject: [PATCH 3/3] A little more cleanup --- API.php | 21 ++------------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/API.php b/API.php index 65eedfdd..db858ca5 100755 --- a/API.php +++ b/API.php @@ -585,15 +585,7 @@ public function editAlert($idAlert, $name, $idSites, $period, $emailMe, $additio * tags={"CustomAlerts"}, * @OA\Parameter(ref="#/components/parameters/module"), * @OA\Parameter(ref="#/components/parameters/format"), - * @OA\Parameter( - * name="idAlert", - * in="query", - * description="The ID of the alert", - * required=true, - * @OA\Schema( - * type="integer" - * ) - * ), + * @OA\Parameter(ref="#/components/parameters/idAlert"), * @OA\Response( * response="200", * description="200 response without body" @@ -621,16 +613,7 @@ public function deleteAlert($idAlert) * tags={"CustomAlerts"}, * @OA\Parameter(ref="#/components/parameters/module"), * @OA\Parameter(ref="#/components/parameters/format"), - * @OA\Parameter( - * name="idSites", - * in="query", - * description="The IDs of the sites to filter alerts by", - * required=true, - * @OA\Schema( - * type="array", - * @OA\Items(type="integer") - * ) - * ), + * @OA\Parameter(ref="#/components/parameters/alertIdSites"), * @OA\Response( * response="200", * description="A collection of alerts matching the sites",