From 702b5dbc2a3c7e573963f647fd2c4e629c860094 Mon Sep 17 00:00:00 2001
From: jld3103 <jld3103yt@gmail.com>
Date: Mon, 27 Feb 2023 16:47:46 +0100
Subject: [PATCH] oauth2: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>
---
 .../Controller/LoginRedirectorController.php   | 18 ++++++++++++------
 .../lib/Controller/OauthApiController.php      | 18 ++++++++++++------
 apps/oauth2/openapi.json                       |  2 +-
 3 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/apps/oauth2/lib/Controller/LoginRedirectorController.php b/apps/oauth2/lib/Controller/LoginRedirectorController.php
index 57f18a97f85c5..b8b09c80b2722 100644
--- a/apps/oauth2/lib/Controller/LoginRedirectorController.php
+++ b/apps/oauth2/lib/Controller/LoginRedirectorController.php
@@ -8,6 +8,7 @@
  * @author Daniel Kesselberg <mail@danielkesselberg.de>
  * @author Lukas Reschke <lukas@statuscode.ch>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -30,8 +31,8 @@
 use OCA\OAuth2\Db\ClientMapper;
 use OCA\OAuth2\Exceptions\ClientNotFoundException;
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\RedirectResponse;
-use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Http\TemplateResponse;
 use OCP\IL10N;
 use OCP\IRequest;
@@ -74,14 +75,19 @@ public function __construct(string $appName,
 	 * @NoCSRFRequired
 	 * @UseSession
 	 *
-	 * @param string $client_id
-	 * @param string $state
-	 * @param string $response_type
-	 * @return Response
+	 * Authorize the user
+	 *
+	 * @param string $client_id Client ID
+	 * @param string $state State of the flow
+	 * @param string $response_type Response type for the flow
+	 * @return TemplateResponse<Http::STATUS_OK, array{}>|RedirectResponse<Http::STATUS_SEE_OTHER, array{}>
+	 *
+	 * 200: Client not found
+	 * 303: Redirect to login URL
 	 */
 	public function authorize($client_id,
 							  $state,
-							  $response_type): Response {
+							  $response_type) {
 		try {
 			$client = $this->clientMapper->getByIdentifier($client_id);
 		} catch (ClientNotFoundException $e) {
diff --git a/apps/oauth2/lib/Controller/OauthApiController.php b/apps/oauth2/lib/Controller/OauthApiController.php
index e07a2c2de1579..8cdd813244176 100644
--- a/apps/oauth2/lib/Controller/OauthApiController.php
+++ b/apps/oauth2/lib/Controller/OauthApiController.php
@@ -8,6 +8,7 @@
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  * @author Lukas Reschke <lukas@statuscode.ch>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -66,12 +67,17 @@ public function __construct(
 	 * @NoCSRFRequired
 	 * @BruteForceProtection(action=oauth2GetToken)
 	 *
-	 * @param string $grant_type
-	 * @param string $code
-	 * @param string $refresh_token
-	 * @param string $client_id
-	 * @param string $client_secret
-	 * @return JSONResponse
+	 * Get a token
+	 *
+	 * @param string $grant_type Token type that should be granted
+	 * @param string $code Code of the flow
+	 * @param string $refresh_token Refresh token
+	 * @param string $client_id Client ID
+	 * @param string $client_secret Client secret
+	 * @return JSONResponse<Http::STATUS_OK, array{access_token: string, token_type: string, expires_in: int, refresh_token: string, user_id: string}, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 *
+	 * 200: Token returned
+	 * 400: Getting token is not possible
 	 */
 	public function getToken($grant_type, $code, $refresh_token, $client_id, $client_secret): JSONResponse {
 
diff --git a/apps/oauth2/openapi.json b/apps/oauth2/openapi.json
index 57a7bee1a64b4..a9903ae3473e5 100644
--- a/apps/oauth2/openapi.json
+++ b/apps/oauth2/openapi.json
@@ -19,7 +19,7 @@
                 "scheme": "bearer"
             }
         },
-        "schemas": []
+        "schemas": {}
     },
     "paths": {
         "/index.php/apps/oauth2/authorize": {