From a353b78bda33fa3eb8ec26419c1b8b439a2edd61 Mon Sep 17 00:00:00 2001 From: jld3103 Date: Tue, 21 Mar 2023 08:55:19 +0100 Subject: [PATCH] weather_status: Add OpenAPI spec Signed-off-by: jld3103 --- .../composer/composer/autoload_classmap.php | 1 + .../composer/composer/autoload_static.php | 1 + apps/weather_status/lib/Capabilities.php | 3 + .../Controller/WeatherStatusController.php | 23 +++-- .../lib/ResponseDefinitions.php | 87 +++++++++++++++++++ .../lib/Service/WeatherStatusService.php | 5 +- 6 files changed, 109 insertions(+), 11 deletions(-) create mode 100644 apps/weather_status/lib/ResponseDefinitions.php diff --git a/apps/weather_status/composer/composer/autoload_classmap.php b/apps/weather_status/composer/composer/autoload_classmap.php index 88bc5078d54..00626b48042 100644 --- a/apps/weather_status/composer/composer/autoload_classmap.php +++ b/apps/weather_status/composer/composer/autoload_classmap.php @@ -10,5 +10,6 @@ return array( 'OCA\\WeatherStatus\\AppInfo\\Application' => $baseDir . '/../lib/AppInfo/Application.php', 'OCA\\WeatherStatus\\Capabilities' => $baseDir . '/../lib/Capabilities.php', 'OCA\\WeatherStatus\\Controller\\WeatherStatusController' => $baseDir . '/../lib/Controller/WeatherStatusController.php', + 'OCA\\WeatherStatus\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php', 'OCA\\WeatherStatus\\Service\\WeatherStatusService' => $baseDir . '/../lib/Service/WeatherStatusService.php', ); diff --git a/apps/weather_status/composer/composer/autoload_static.php b/apps/weather_status/composer/composer/autoload_static.php index eb0ecea7954..1891eb468e2 100644 --- a/apps/weather_status/composer/composer/autoload_static.php +++ b/apps/weather_status/composer/composer/autoload_static.php @@ -25,6 +25,7 @@ class ComposerStaticInitWeatherStatus 'OCA\\WeatherStatus\\AppInfo\\Application' => __DIR__ . '/..' . '/../lib/AppInfo/Application.php', 'OCA\\WeatherStatus\\Capabilities' => __DIR__ . '/..' . '/../lib/Capabilities.php', 'OCA\\WeatherStatus\\Controller\\WeatherStatusController' => __DIR__ . '/..' . '/../lib/Controller/WeatherStatusController.php', + 'OCA\\WeatherStatus\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php', 'OCA\\WeatherStatus\\Service\\WeatherStatusService' => __DIR__ . '/..' . '/../lib/Service/WeatherStatusService.php', ); 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 */ 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 */ 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 */ 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 */ 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|DataResponse + * + * 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 */ 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 */ 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 @@ + + * + * @author Kate Döen + * + * @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 . + * + */ + +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 { -- 2.39.5