Skip to content

Commit 089efa6

Browse files
provokateurinprovokateurin
committed
oauth2: Add OpenAPI spec
Signed-off-by: jld3103 <jld3103yt@gmail.com>
1 parent 544e030 commit 089efa6

File tree

3 files changed

+222
-11
lines changed

3 files changed

+222
-11
lines changed

‎apps/oauth2/lib/Controller/LoginRedirectorController.php‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
* @author Daniel Kesselberg <mail@danielkesselberg.de>
99
* @author Lukas Reschke <lukas@statuscode.ch>
1010
* @author Roeland Jago Douma <roeland@famdouma.nl>
11+
* @author Kate Döen <kate.doeen@nextcloud.com>
1112
*
1213
* @license GNU AGPL version 3 or any later version
1314
*
@@ -27,6 +28,7 @@
2728
*/
2829
namespace OCA\OAuth2\Controller;
2930

31+
use OC\AppFramework\Http;
3032
use OCA\OAuth2\Db\ClientMapper;
3133
use OCA\OAuth2\Exceptions\ClientNotFoundException;
3234
use OCP\AppFramework\Controller;
@@ -74,14 +76,19 @@ public function __construct(string $appName,
7476
* @NoCSRFRequired
7577
* @UseSession
7678
*
77-
* @param string $client_id
78-
* @param string $state
79-
* @param string $response_type
80-
* @return Response
79+
* Authorize the user
80+
*
81+
* @param string $client_id Client ID
82+
* @param string $state State of the flow
83+
* @param string $response_type Response type for the flow
84+
* @return TemplateResponse<Http::STATUS_OK>|RedirectResponse
85+
*
86+
* 200: Client not found
87+
* 303: Redirect to login URL
8188
*/
8289
public function authorize($client_id,
8390
$state,
84-
$response_type): Response {
91+
$response_type) {
8592
try {
8693
$client = $this->clientMapper->getByIdentifier($client_id);
8794
} catch (ClientNotFoundException $e) {

‎apps/oauth2/lib/Controller/OauthApiController.php‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
* @author Christoph Wurst <christoph@winzerhof-wurst.at>
99
* @author Lukas Reschke <lukas@statuscode.ch>
1010
* @author Roeland Jago Douma <roeland@famdouma.nl>
11+
* @author Kate Döen <kate.doeen@nextcloud.com>
1112
*
1213
* @license GNU AGPL version 3 or any later version
1314
*
@@ -82,12 +83,17 @@ public function __construct(string $appName,
8283
* @PublicPage
8384
* @NoCSRFRequired
8485
*
85-
* @param string $grant_type
86-
* @param string $code
87-
* @param string $refresh_token
88-
* @param string $client_id
89-
* @param string $client_secret
90-
* @return JSONResponse
86+
* Get a token
87+
*
88+
* @param string $grant_type Token type that should be granted
89+
* @param string $code Code of the flow
90+
* @param string $refresh_token Refresh token
91+
* @param string $client_id Client ID
92+
* @param string $client_secret Client secret
93+
* @return JSONResponse<array{access_token: string, token_type: string, expires_in: int, refresh_token: string, user_id: string}, Http::STATUS_OK>|JSONResponse<array{error: string}, Http::STATUS_BAD_REQUEST>
94+
*
95+
* 200: Token returned
96+
* 400: Getting token is not possible
9197
*/
9298
public function getToken($grant_type, $code, $refresh_token, $client_id, $client_secret): JSONResponse {
9399

‎apps/oauth2/openapi.json‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
{
2+
"openapi": "3.0.3",
3+
"info": {
4+
"title": "OAuth 2.0",
5+
"description": "Allows OAuth2 compatible authentication from other web applications.",
6+
"license": {
7+
"name": "agpl"
8+
},
9+
"version": "1.14.0"
10+
},
11+
"paths": {
12+
"/index.php/apps/oauth2/authorize": {
13+
"get": {
14+
"tags": [
15+
"login_redirector"
16+
],
17+
"summary": "Authorize the user",
18+
"operationId": "login_redirector-authorize",
19+
"parameters": [
20+
{
21+
"name": "client_id",
22+
"in": "query",
23+
"description": "Client ID",
24+
"required": true,
25+
"schema": {
26+
"type": "string"
27+
}
28+
},
29+
{
30+
"name": "state",
31+
"in": "query",
32+
"description": "State of the flow",
33+
"required": true,
34+
"schema": {
35+
"type": "string"
36+
}
37+
},
38+
{
39+
"name": "response_type",
40+
"in": "query",
41+
"description": "Response type for the flow",
42+
"required": true,
43+
"schema": {
44+
"type": "string"
45+
}
46+
}
47+
],
48+
"responses": {
49+
"200": {
50+
"description": "Client not found",
51+
"content": {
52+
"text/html": {
53+
"schema": {
54+
"type": "string"
55+
}
56+
}
57+
}
58+
},
59+
"303": {
60+
"description": "Redirect to login URL",
61+
"headers": {
62+
"Location": {
63+
"schema": {
64+
"type": "string"
65+
}
66+
}
67+
}
68+
}
69+
}
70+
}
71+
},
72+
"/index.php/apps/oauth2/api/v1/token": {
73+
"post": {
74+
"tags": [
75+
"oauth_api"
76+
],
77+
"summary": "Get a token",
78+
"operationId": "oauth_api-get-token",
79+
"parameters": [
80+
{
81+
"name": "grant_type",
82+
"in": "query",
83+
"description": "Token type that should be granted",
84+
"required": true,
85+
"schema": {
86+
"type": "string"
87+
}
88+
},
89+
{
90+
"name": "code",
91+
"in": "query",
92+
"description": "Code of the flow",
93+
"required": true,
94+
"schema": {
95+
"type": "string"
96+
}
97+
},
98+
{
99+
"name": "refresh_token",
100+
"in": "query",
101+
"description": "Refresh token",
102+
"required": true,
103+
"schema": {
104+
"type": "string"
105+
}
106+
},
107+
{
108+
"name": "client_id",
109+
"in": "query",
110+
"description": "Client ID",
111+
"required": true,
112+
"schema": {
113+
"type": "string"
114+
}
115+
},
116+
{
117+
"name": "client_secret",
118+
"in": "query",
119+
"description": "Client secret",
120+
"required": true,
121+
"schema": {
122+
"type": "string"
123+
}
124+
}
125+
],
126+
"responses": {
127+
"200": {
128+
"description": "Token returned",
129+
"content": {
130+
"application/json": {
131+
"schema": {
132+
"required": [
133+
"access_token",
134+
"token_type",
135+
"expires_in",
136+
"refresh_token",
137+
"user_id"
138+
],
139+
"type": "object",
140+
"properties": {
141+
"access_token": {
142+
"type": "string"
143+
},
144+
"token_type": {
145+
"type": "string"
146+
},
147+
"expires_in": {
148+
"type": "integer"
149+
},
150+
"refresh_token": {
151+
"type": "string"
152+
},
153+
"user_id": {
154+
"type": "string"
155+
}
156+
}
157+
}
158+
}
159+
}
160+
},
161+
"400": {
162+
"description": "Getting token is not possible",
163+
"content": {
164+
"application/json": {
165+
"schema": {
166+
"required": [
167+
"error"
168+
],
169+
"type": "object",
170+
"properties": {
171+
"error": {
172+
"type": "string"
173+
}
174+
}
175+
}
176+
}
177+
}
178+
}
179+
}
180+
}
181+
}
182+
},
183+
"components": {
184+
"schemas": {},
185+
"securitySchemes": {
186+
"basic_auth": {
187+
"type": "http",
188+
"scheme": "basic"
189+
}
190+
}
191+
},
192+
"security": [
193+
{
194+
"basic_auth": []
195+
}
196+
],
197+
"tags": []
198+
}

0 commit comments

Comments
 (0)