weather_status: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>

4 files changed, 107 insertions, 11 deletions

diff --git a/apps/weather_status/lib/Capabilities.php b/apps/weather_status/lib/Capabilities.php
index 60cbb4602fd..b7362a88688 100644
--- a/apps/weather_status/lib/Capabilities.php
+++ b/apps/weather_status/lib/Capabilities.php
@@ -43,6 +43,9 @@ class Capabilities implements ICapability {
 	public function __construct() {
 	}
 
+	/**
+	 * @return array{weather_status: array{enabled: bool}}
+	 */
 	public function getCapabilities() {
 		return [
 			Application::APP_ID => [
diff --git a/apps/weather_status/lib/Controller/WeatherStatusController.php b/apps/weather_status/lib/Controller/WeatherStatusController.php
index 01bdf78f410..1a5524967b5 100644
--- a/apps/weather_status/lib/Controller/WeatherStatusController.php
+++ b/apps/weather_status/lib/Controller/WeatherStatusController.php
@@ -25,6 +25,7 @@ declare(strict_types=1);
  */
 namespace OCA\WeatherStatus\Controller;
 
+use OCA\WeatherStatus\ResponseDefinitions;
 use OCA\WeatherStatus\Service\WeatherStatusService;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
@@ -32,6 +33,9 @@ use OCP\AppFramework\OCSController;
 use OCP\ILogger;
 use OCP\IRequest;
 
+/**
+ * @psalm-import-type WeatherStatusForecast from ResponseDefinitions
+ */
 class WeatherStatusController extends OCSController {
 
 	/** @var string */
@@ -59,7 +63,7 @@ class WeatherStatusController extends OCSController {
 	 *
 	 * Try to use the address set in user personal settings as weather location
 	 *
-	 * @return DataResponse with success state and address information
+	 * @return DataResponse<Http::STATUS_OK, array{success: bool, lat: ?float, lon: ?float, address: ?string}, array{}>
 	 */
 	public function usePersonalAddress(): DataResponse {
 		return new DataResponse($this->service->usePersonalAddress());
@@ -73,7 +77,7 @@ class WeatherStatusController extends OCSController {
 	 * - use the user defined address
 	 *
 	 * @param int $mode New mode
-	 * @return DataResponse success state
+	 * @return DataResponse<Http::STATUS_OK, array{success: bool}, array{}>
 	 */
 	public function setMode(int $mode): DataResponse {
 		return new DataResponse($this->service->setMode($mode));
@@ -88,7 +92,7 @@ class WeatherStatusController extends OCSController {
 	 * @param string|null $address Any approximative or exact address
 	 * @param float|null $lat Latitude in decimal degree format
 	 * @param float|null $lon Longitude in decimal degree format
-	 * @return DataResponse with success state and address information
+	 * @return DataResponse<Http::STATUS_OK, array{success: bool, lat: ?float, lon: ?float, address: ?string}, array{}>
 	 */
 	public function setLocation(?string $address, ?float $lat, ?float $lon): DataResponse {
 		$currentWeather = $this->service->setLocation($address, $lat, $lon);
@@ -100,7 +104,7 @@ class WeatherStatusController extends OCSController {
 	 *
 	 * Get stored user location
 	 *
-	 * @return DataResponse which contains coordinates, formatted address and current weather status mode
+	 * @return DataResponse<Http::STATUS_OK, array{lat: float, lon: float, address: string, mode: int}, array{}>
 	 */
 	public function getLocation(): DataResponse {
 		$location = $this->service->getLocation();
@@ -112,7 +116,10 @@ class WeatherStatusController extends OCSController {
 	 *
 	 * Get forecast for current location
 	 *
-	 * @return DataResponse which contains success state and filtered forecast data
+	 * @return DataResponse<Http::STATUS_OK, WeatherStatusForecast[], array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{success: bool}, array{}>
+	 *
+	 * 200: Forecast returned
+	 * 404: Forecast not found
 	 */
 	public function getForecast(): DataResponse {
 		$forecast = $this->service->getForecast();
@@ -128,7 +135,7 @@ class WeatherStatusController extends OCSController {
 	 *
 	 * Get favorites list
 	 *
-	 * @return DataResponse which contains the favorite list
+	 * @return DataResponse<Http::STATUS_OK, string[], array{}>
 	 */
 	public function getFavorites(): DataResponse {
 		return new DataResponse($this->service->getFavorites());
@@ -139,8 +146,8 @@ class WeatherStatusController extends OCSController {
 	 *
 	 * Set favorites list
 	 *
-	 * @param array $favorites
-	 * @return DataResponse success state
+	 * @param string[] $favorites Favorite addresses
+	 * @return DataResponse<Http::STATUS_OK, array{success: bool}, array{}>
 	 */
 	public function setFavorites(array $favorites): DataResponse {
 		return new DataResponse($this->service->setFavorites($favorites));
diff --git a/apps/weather_status/lib/ResponseDefinitions.php b/apps/weather_status/lib/ResponseDefinitions.php
new file mode 100644
index 00000000000..08f8049b964
--- /dev/null
+++ b/apps/weather_status/lib/ResponseDefinitions.php
@@ -0,0 +1,87 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @author Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCA\WeatherStatus;
+
+/**
+ * https://api.met.no/doc/ForecastJSON
+ * @psalm-type WeatherStatusForecast = array{
+ *     time: string,
+ *     data: array{
+ *         instant: array{
+ *             details: array{
+ *                 air_pressure_at_sea_level: float,
+ *                 air_temperature: float,
+ *                 cloud_area_fraction: float,
+ *                 cloud_area_fraction_high: float,
+ *                 cloud_area_fraction_low: float,
+ *                 cloud_area_fraction_medium: float,
+ *                 dew_point_temperature: float,
+ *                 fog_area_fraction: float,
+ *                 relative_humidity: float,
+ *                 ultraviolet_index_clear_sky: float,
+ *                 wind_from_direction: float,
+ *                 wind_speed: float,
+ *                 wind_speed_of_gust: float,
+ *             },
+ *         },
+ *         next_12_hours: array{
+ *             summary: array{
+ *                 symbol_code: string,
+ *             },
+ *             details: array{
+ *                 probability_of_precipitation: float,
+ *             },
+ *         },
+ *         next_1_hours: array{
+ *             summary: array{
+ *                 symbol_code: string,
+ *             },
+ *             details: array{
+ *                 precipitation_amount: float,
+ *                 precipitation_amount_max: float,
+ *                 precipitation_amount_min: float,
+ *                 probability_of_precipitation: float,
+ *                 probability_of_thunder: float,
+ *             },
+ *         },
+ *         next_6_hours: array{
+ *             summary: array{
+ *                 symbol_code: string,
+ *             },
+ *             details: array{
+ *                 air_temperature_max: float,
+ *                 air_temperature_min: float,
+ *                 precipitation_amount: float,
+ *                 precipitation_amount_max: float,
+ *                 precipitation_amount_min: float,
+ *                 probability_of_precipitation: float,
+ *             },
+ *         },
+ *     },
+ * }
+ */
+class ResponseDefinitions {
+}
diff --git a/apps/weather_status/lib/Service/WeatherStatusService.php b/apps/weather_status/lib/Service/WeatherStatusService.php
index b334a5e3ba3..d54c7baeb1f 100644
--- a/apps/weather_status/lib/Service/WeatherStatusService.php
+++ b/apps/weather_status/lib/Service/WeatherStatusService.php
@@ -131,8 +131,7 @@ class WeatherStatusService {
 
 	/**
 	 * Get favorites list
-	 * @param array $favorites
-	 * @return array success state
+	 * @return string[]
 	 */
 	public function getFavorites(): array {
 		$favoritesJson = $this->config->getUserValue($this->userId, Application::APP_ID, 'favorites', '');
@@ -141,7 +140,7 @@ class WeatherStatusService {
 
 	/**
 	 * Set favorites list
-	 * @param array $favorites
+	 * @param string[] $favorites
 	 * @return array success state
 	 */
 	public function setFavorites(array $favorites): array {