Skip to content

Commit b31891f

Browse files
provokateurinprovokateurin
committed
weather_status: Add OpenAPI spec
Signed-off-by: jld3103 <jld3103yt@gmail.com>
1 parent 6a9b90f commit b31891f

File tree

5 files changed

+1021
-11
lines changed

5 files changed

+1021
-11
lines changed

‎apps/weather_status/lib/Capabilities.php

+2
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@ public function __construct() {
4545

4646
/**
4747
* @inheritDoc
48+
*
49+
* @return array{weather_status: array{enabled: bool}}
4850
*/
4951
public function getCapabilities() {
5052
return [

‎apps/weather_status/lib/Controller/WeatherStatusController.php

+15-8
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,17 @@
2525
*/
2626
namespace OCA\WeatherStatus\Controller;
2727

28+
use OCA\WeatherStatus\ResponseDefinitions;
2829
use OCA\WeatherStatus\Service\WeatherStatusService;
2930
use OCP\AppFramework\Http;
3031
use OCP\AppFramework\Http\DataResponse;
3132
use OCP\AppFramework\OCSController;
3233
use OCP\ILogger;
3334
use OCP\IRequest;
3435

36+
/**
37+
* @psalm-import-type WeatherStatusForecast from ResponseDefinitions
38+
*/
3539
class WeatherStatusController extends OCSController {
3640

3741
/** @var string */
@@ -59,7 +63,7 @@ public function __construct(string $appName,
5963
*
6064
* Try to use the address set in user personal settings as weather location
6165
*
62-
* @return DataResponse with success state and address information
66+
* @return DataResponse<array{success: bool, lat: ?float, lon: ?float, address: ?string}, Http::STATUS_OK>
6367
*/
6468
public function usePersonalAddress(): DataResponse {
6569
return new DataResponse($this->service->usePersonalAddress());
@@ -73,7 +77,7 @@ public function usePersonalAddress(): DataResponse {
7377
* - use the user defined address
7478
*
7579
* @param int $mode New mode
76-
* @return DataResponse success state
80+
* @return DataResponse<array{success: bool}, Http::STATUS_OK>
7781
*/
7882
public function setMode(int $mode): DataResponse {
7983
return new DataResponse($this->service->setMode($mode));
@@ -88,7 +92,7 @@ public function setMode(int $mode): DataResponse {
8892
* @param string|null $address Any approximative or exact address
8993
* @param float|null $lat Latitude in decimal degree format
9094
* @param float|null $lon Longitude in decimal degree format
91-
* @return DataResponse with success state and address information
95+
* @return DataResponse<array{success: bool, lat: ?float, lon: ?float, address: ?string}, Http::STATUS_OK>
9296
*/
9397
public function setLocation(?string $address, ?float $lat, ?float $lon): DataResponse {
9498
$currentWeather = $this->service->setLocation($address, $lat, $lon);
@@ -100,7 +104,7 @@ public function setLocation(?string $address, ?float $lat, ?float $lon): DataRes
100104
*
101105
* Get stored user location
102106
*
103-
* @return DataResponse which contains coordinates, formatted address and current weather status mode
107+
* @return DataResponse<array{lat: float, lon: float, address: string, mode: int}, Http::STATUS_OK>
104108
*/
105109
public function getLocation(): DataResponse {
106110
$location = $this->service->getLocation();
@@ -112,7 +116,10 @@ public function getLocation(): DataResponse {
112116
*
113117
* Get forecast for current location
114118
*
115-
* @return DataResponse which contains success state and filtered forecast data
119+
* @return DataResponse<WeatherStatusForecast[], Http::STATUS_OK>|DataResponse<array{success: bool}, Http::STATUS_NOT_FOUND>
120+
*
121+
* 200: Forecast returned
122+
* 404: Forecast not found
116123
*/
117124
public function getForecast(): DataResponse {
118125
$forecast = $this->service->getForecast();
@@ -128,7 +135,7 @@ public function getForecast(): DataResponse {
128135
*
129136
* Get favorites list
130137
*
131-
* @return DataResponse which contains the favorite list
138+
* @return DataResponse<string[], Http::STATUS_OK>
132139
*/
133140
public function getFavorites(): DataResponse {
134141
return new DataResponse($this->service->getFavorites());
@@ -139,8 +146,8 @@ public function getFavorites(): DataResponse {
139146
*
140147
* Set favorites list
141148
*
142-
* @param array $favorites
143-
* @return DataResponse success state
149+
* @param string[] $favorites Favorite addresses
150+
* @return DataResponse<array{success: bool}, Http::STATUS_OK>
144151
*/
145152
public function setFavorites(array $favorites): DataResponse {
146153
return new DataResponse($this->service->setFavorites($favorites));

‎apps/weather_status/lib/ResponseDefinitions.php

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
<?php
2+
declare(strict_types=1);
3+
4+
/**
5+
* @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com>
6+
*
7+
* @author Kate Döen <kate.doeen@nextcloud.com>
8+
*
9+
* @license GNU AGPL version 3 or any later version
10+
*
11+
* This program is free software: you can redistribute it and/or modify
12+
* it under the terms of the GNU Affero General Public License as
13+
* published by the Free Software Foundation, either version 3 of the
14+
* License, or (at your option) any later version.
15+
*
16+
* This program is distributed in the hope that it will be useful,
17+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
18+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19+
* GNU Affero General Public License for more details.
20+
*
21+
* You should have received a copy of the GNU Affero General Public License
22+
* along with this program. If not, see <http://www.gnu.org/licenses/>.
23+
*
24+
*/
25+
26+
namespace OCA\WeatherStatus;
27+
28+
/**
29+
* https://api.met.no/doc/ForecastJSON
30+
* @psalm-type WeatherStatusForecast = array{
31+
* time: string,
32+
* data: array{
33+
* instant: array{
34+
* details: array{
35+
* air_pressure_at_sea_level: float,
36+
* air_temperature: float,
37+
* cloud_area_fraction: float,
38+
* cloud_area_fraction_high: float,
39+
* cloud_area_fraction_low: float,
40+
* cloud_area_fraction_medium: float,
41+
* dew_point_temperature: float,
42+
* fog_area_fraction: float,
43+
* relative_humidity: float,
44+
* ultraviolet_index_clear_sky: float,
45+
* wind_from_direction: float,
46+
* wind_speed: float,
47+
* wind_speed_of_gust: float,
48+
* },
49+
* },
50+
* next_12_hours: array{
51+
* summary: array{
52+
* symbol_code: string,
53+
* },
54+
* details: array{
55+
* probability_of_precipitation: float,
56+
* },
57+
* },
58+
* next_1_hours: array{
59+
* summary: array{
60+
* symbol_code: string,
61+
* },
62+
* details: array{
63+
* precipitation_amount: float,
64+
* precipitation_amount_max: float,
65+
* precipitation_amount_min: float,
66+
* probability_of_precipitation: float,
67+
* probability_of_thunder: float,
68+
* },
69+
* },
70+
* next_6_hours: array{
71+
* summary: array{
72+
* symbol_code: string,
73+
* },
74+
* details: array{
75+
* air_temperature_max: float,
76+
* air_temperature_min: float,
77+
* precipitation_amount: float,
78+
* precipitation_amount_max: float,
79+
* precipitation_amount_min: float,
80+
* probability_of_precipitation: float,
81+
* },
82+
* },
83+
* },
84+
* }
85+
*/
86+
class ResponseDefinitions {
87+
}

‎apps/weather_status/lib/Service/WeatherStatusService.php

+2-3
Original file line numberDiff line numberDiff line change
@@ -131,8 +131,7 @@ public function setMode(int $mode): array {
131131

132132
/**
133133
* Get favorites list
134-
* @param array $favorites
135-
* @return array success state
134+
* @return string[]
136135
*/
137136
public function getFavorites(): array {
138137
$favoritesJson = $this->config->getUserValue($this->userId, Application::APP_ID, 'favorites', '');
@@ -141,7 +140,7 @@ public function getFavorites(): array {
141140

142141
/**
143142
* Set favorites list
144-
* @param array $favorites
143+
* @param string[] $favorites
145144
* @return array success state
146145
*/
147146
public function setFavorites(array $favorites): array {

0 commit comments

Comments
 (0)