fix: Add 401 response for non-public pages and 403 response for admin pages

Signed-off-by: provokateurin <kate@provokateurin.de>

Author: provokateurin

generate-spec.php

@@ -466,7 +466,6 @@
 		$isIgnored = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'IgnoreOpenAPI');
 		$isPasswordConfirmation = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'PasswordConfirmationRequired');
 		$isExApp = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'ExAppRequired');
-		$isCORS = Helpers::classMethodHasAnnotationOrAttribute($methodFunction, 'CORS');
 		$scopes = Helpers::getOpenAPIAttributeScopes($classMethod, $routeName);
 
 		if ($isIgnored) {
@@ -520,7 +519,7 @@
 			];
 		}
 
-		$classMethodInfo = ControllerMethod::parse($routeName, $definitions, $methodFunction, $isAdmin, $isDeprecated, $isPasswordConfirmation, $isCORS);
+		$classMethodInfo = ControllerMethod::parse($routeName, $definitions, $methodFunction, $isPublic, $isAdmin, $isDeprecated, $isPasswordConfirmation, $isCORS, $isOCS);
 		if (count($classMethodInfo->responses) == 0) {
 			Logger::error($routeName, 'Returns no responses');
 			continue;

src/ControllerMethod.php

@@ -304,10 +304,12 @@ public function __construct(
 	public static function parse(string $context,
 		array $definitions,
 		ClassMethod $method,
+		bool $isPublic,
 		bool $isAdmin,
 		bool $isDeprecated,
 		bool $isPasswordConfirmation,
 		bool $isCORS,
+		bool $isOCS,
 	): ControllerMethod {
 		global $phpDocParser, $lexer, $nodeFinder, $allowMissingDocs;
 
@@ -409,6 +411,46 @@ public static function parse(string $context,
 			Logger::error($context, 'Missing @return annotation');
 		}
 
+		if (!$isPublic || $isAdmin) {
+			$statusCodes = [];
+			if (!$isPublic) {
+				$responseDescriptions[401] ??= 'Current user is not logged in';
+				$statusCodes[] = 401;
+			}
+			if ($isAdmin) {
+				$responseDescriptions[403] ??= 'Logged in account must be an admin';
+				$statusCodes[] = 403;
+			}
+
+			foreach ($statusCodes as $statusCode) {
+				if ($isOCS) {
+					$responses[] = new ControllerMethodResponse(
+						'DataResponse',
+						$statusCode,
+						'application/json',
+						new OpenApiType($context),
+					);
+				} else {
+					$responses[] = new ControllerMethodResponse(
+						'JsonResponse',
+						$statusCode,
+						'application/json',
+						new OpenApiType(
+							$context,
+							type: 'object',
+							properties: [
+								'message' => new OpenApiType(
+									$context,
+									type: 'string',
+								),
+							],
+							required: ['message'],
+						),
+					);
+				}
+			}
+		}
+
 		$responseStatusCodes = array_unique(array_map(static fn (ControllerMethodResponse $response): int => $response->statusCode, $responses));
 		$unusedResponseDescriptions = array_diff(array_keys($responseDescriptions), $responseStatusCodes);
 		if ($unusedResponseDescriptions !== []) {

src/Helpers.php

@@ -140,8 +140,8 @@ public static function wrapOCSResponse(Route $route, ControllerMethodResponse $r
 		return $schema;
 	}
 
-	public static function cleanEmptyResponseArray(array $schema): array|stdClass {
-		if (array_key_exists('type', $schema) && $schema['type'] === 'array' && array_key_exists('maxItems', $schema) && $schema['maxItems'] === 0) {
+	public static function cleanEmptyResponseArray(array|stdClass $schema): array|stdClass {
+		if (is_array($schema) && array_key_exists('type', $schema) && $schema['type'] === 'array' && array_key_exists('maxItems', $schema) && $schema['maxItems'] === 0) {
 			return new stdClass();
 		}
 

tests/appinfo/routes.php

@@ -91,6 +91,8 @@
 		['name' => 'Settings#publicPageAnnotation', 'url' => '/api/{apiVersion}/public-page/annotation', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
 		['name' => 'Settings#publicPageAttribute', 'url' => '/api/{apiVersion}/public-page/attribute', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
 		['name' => 'Settings#mergedResponses', 'url' => '/api/{apiVersion}/merged-responses', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
+		['name' => 'Settings#custom401', 'url' => '/api/{apiVersion}/custom/401', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
+		['name' => 'Settings#custom403', 'url' => '/api/{apiVersion}/custom/403', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
 		['name' => 'V1\SubDir#subDirRoute', 'url' => '/sub-dir', 'verb' => 'GET'],
 	],
 ];

tests/lib/Controller/SettingsController.php

@@ -13,6 +13,7 @@
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\CORS;
 use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
+use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PasswordConfirmationRequired;
 use OCP\AppFramework\Http\Attribute\PublicPage;
@@ -827,4 +828,27 @@ public function publicPageAttribute(): DataResponse {
 	public function mergedResponses(): DataResponse|JSONResponse {
 		return new DataResponse();
 	}
+
+	/**
+	 * A page with a custom 401.
+	 *
+	 * @return DataResponse<Http::STATUS_UNAUTHORIZED, array{a: string}, array{}>
+	 *
+	 * 401: Admin settings updated
+	 */
+	#[NoAdminRequired]
+	public function custom401(): DataResponse {
+		return new DataResponse();
+	}
+
+	/**
+	 * A page with a custom 403.
+	 *
+	 * @return DataResponse<Http::STATUS_FORBIDDEN, array{a: string}, array{}>
+	 *
+	 * 403: Admin settings updated
+	 */
+	public function custom403(): DataResponse {
+		return new DataResponse();
+	}
 }