Skip to content

Commit dea9f87

Browse files
pasibunpasibun
authored
Merge pull request #18 from developer-overheid-nl/17-oas-update
refactor: Update Keycloak client description for clarity and accuracy
2 parents a140a99 + 3eae365 commit dea9f87

7 files changed

Lines changed: 62 additions & 492 deletions

File tree

‎api/openapi.json‎

Lines changed: 55 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
"name": "Team developer.overheid.nl",
77
"url": "https://github.com/developer-overheid-nl/don-tools-api/issues"
88
},
9-
"description": "API van het Tools (apis.developer.overheid.nl)",
9+
"description": "API to access the tools endpoints of developer.overheid.nl.\n\n## Auth\n\nThis API provides tools endpoints that can be accessed with either an API key or a client credentials token.\n\n### API key\n\nUsing an API key, you can access the tools endpoints.\nThese requests can also be made from the browser.\nRequest a read-only API key at https://apis.developer.overheid.nl/apis/key-aanvragen.\nSimply pass the obtained API key with each request using the `X-Api-Key` header.\n\n### Client credentials token\n\nUsing a client credentials token, you can access the tools endpoints.\nTo obtain the token, perform a `POST` request to `https://auth.developer.overheid.nl/realms/don/protocol/openid-connect/token` with the following Form URL Encoded body:\n- `grant_type`: `client_credentials`\n- `scope`: `tools`\n- `client_id`: the client id you received from us\n- `client_secret`: the client secret you received from us\n\nPass the obtained token with each request using the `Authorization` header. Example:\n\n`Authorization`: `Bearer {ACCESS_TOKEN}` (replace `{ACCESS_TOKEN}` with the obtained `access_token`)",
1010
"title": "Tools API v1",
1111
"version": "1.0.0"
1212
},
@@ -39,7 +39,7 @@
3939
"content": {
4040
"application/json": {
4141
"schema": {
42-
"$ref": "#/components/schemas/OASInput"
42+
"$ref": "#/components/schemas/OasInput"
4343
}
4444
}
4545
}
@@ -66,17 +66,19 @@
6666
}
6767
},
6868
"404": {
69-
"description": "Not Found"
69+
"$ref": "#/components/responses/404"
7070
}
7171
},
7272
"security": [
7373
{
7474
"apiKey": [],
75-
"clientCredentials": ["tools"]
75+
"clientCredentials": []
7676
}
7777
],
7878
"summary": "Arazzo Markdown (POST)",
79-
"tags": ["Tools"],
79+
"tags": [
80+
"Tools"
81+
],
8082
"x-eov-operation-handler": "controllers/ToolsController"
8183
}
8284
},
@@ -88,7 +90,7 @@
8890
"content": {
8991
"application/json": {
9092
"schema": {
91-
"$ref": "#/components/schemas/OASInput"
93+
"$ref": "#/components/schemas/OasInput"
9294
}
9395
}
9496
}
@@ -115,17 +117,19 @@
115117
}
116118
},
117119
"404": {
118-
"description": "Not Found"
120+
"$ref": "#/components/responses/404"
119121
}
120122
},
121123
"security": [
122124
{
123125
"apiKey": [],
124-
"clientCredentials": ["tools"]
126+
"clientCredentials": []
125127
}
126128
],
127129
"summary": "Arazzo Mermaid (POST)",
128-
"tags": ["Tools"],
130+
"tags": [
131+
"Tools"
132+
],
129133
"x-eov-operation-handler": "controllers/ToolsController"
130134
}
131135
},
@@ -164,17 +168,19 @@
164168
}
165169
},
166170
"404": {
167-
"description": "Not Found"
171+
"$ref": "#/components/responses/404"
168172
}
169173
},
170174
"security": [
171175
{
172176
"apiKey": [],
173-
"clientCredentials": ["tools"]
177+
"clientCredentials": []
174178
}
175179
],
176180
"summary": "Maak client (POST)",
177-
"tags": ["Tools"],
181+
"tags": [
182+
"Tools"
183+
],
178184
"x-eov-operation-handler": "controllers/ToolsController"
179185
}
180186
},
@@ -186,7 +192,7 @@
186192
"content": {
187193
"application/json": {
188194
"schema": {
189-
"$ref": "#/components/schemas/OASInput"
195+
"$ref": "#/components/schemas/OasInput"
190196
}
191197
}
192198
}
@@ -206,17 +212,19 @@
206212
}
207213
},
208214
"404": {
209-
"description": "Not Found"
215+
"$ref": "#/components/responses/404"
210216
}
211217
},
212218
"security": [
213219
{
214220
"apiKey": [],
215-
"clientCredentials": ["tools"]
221+
"clientCredentials": []
216222
}
217223
],
218224
"summary": "Converteer OpenAPI 3.0/3.1",
219-
"tags": ["Tools"],
225+
"tags": [
226+
"Tools"
227+
],
220228
"x-eov-operation-handler": "controllers/ToolsController"
221229
}
222230
},
@@ -228,7 +236,7 @@
228236
"content": {
229237
"application/json": {
230238
"schema": {
231-
"$ref": "#/components/schemas/OASInput"
239+
"$ref": "#/components/schemas/OasInput"
232240
}
233241
}
234242
}
@@ -248,17 +256,19 @@
248256
}
249257
},
250258
"404": {
251-
"description": "Not Found"
259+
"$ref": "#/components/responses/404"
252260
}
253261
},
254262
"security": [
255263
{
256264
"apiKey": [],
257-
"clientCredentials": ["tools"]
265+
"clientCredentials": []
258266
}
259267
],
260268
"summary": "Bundle OpenAPI",
261-
"tags": ["Tools"],
269+
"tags": [
270+
"Tools"
271+
],
262272
"x-eov-operation-handler": "controllers/ToolsController"
263273
}
264274
},
@@ -270,7 +280,7 @@
270280
"content": {
271281
"application/json": {
272282
"schema": {
273-
"$ref": "#/components/schemas/OASInput"
283+
"$ref": "#/components/schemas/OasInput"
274284
}
275285
}
276286
}
@@ -297,17 +307,19 @@
297307
}
298308
},
299309
"404": {
300-
"description": "Not Found"
310+
"$ref": "#/components/responses/404"
301311
}
302312
},
303313
"security": [
304314
{
305315
"apiKey": [],
306-
"clientCredentials": ["tools"]
316+
"clientCredentials": []
307317
}
308318
],
309319
"summary": "Generate OpenAPI",
310-
"tags": ["Tools"],
320+
"tags": [
321+
"Tools"
322+
],
311323
"x-eov-operation-handler": "controllers/ToolsController"
312324
}
313325
},
@@ -319,7 +331,7 @@
319331
"content": {
320332
"application/json": {
321333
"schema": {
322-
"$ref": "#/components/schemas/OASInput"
334+
"$ref": "#/components/schemas/OasInput"
323335
}
324336
}
325337
}
@@ -346,17 +358,19 @@
346358
}
347359
},
348360
"404": {
349-
"description": "Not Found"
361+
"$ref": "#/components/responses/404"
350362
}
351363
},
352364
"security": [
353365
{
354366
"apiKey": [],
355-
"clientCredentials": ["tools"]
367+
"clientCredentials": []
356368
}
357369
],
358370
"summary": "Validate OpenAPI (POST)",
359-
"tags": ["Tools"],
371+
"tags": [
372+
"Tools"
373+
],
360374
"x-eov-operation-handler": "controllers/ToolsController"
361375
}
362376
},
@@ -368,7 +382,7 @@
368382
"content": {
369383
"application/json": {
370384
"schema": {
371-
"$ref": "#/components/schemas/OASInput"
385+
"$ref": "#/components/schemas/OasInput"
372386
}
373387
}
374388
}
@@ -388,17 +402,19 @@
388402
}
389403
},
390404
"404": {
391-
"description": "Not Found"
405+
"$ref": "#/components/responses/404"
392406
}
393407
},
394408
"security": [
395409
{
396410
"apiKey": [],
397-
"clientCredentials": ["tools"]
411+
"clientCredentials": []
398412
}
399413
],
400414
"summary": "Maak Postman-collectie (POST)",
401-
"tags": ["Tools"],
415+
"tags": [
416+
"Tools"
417+
],
402418
"x-eov-operation-handler": "controllers/ToolsController"
403419
}
404420
}
@@ -420,13 +436,13 @@
420436
"description": "Resource does not exist",
421437
"headers": {
422438
"API-Version": {
423-
"$ref": "#/headers/API-Version"
439+
"$ref": "#/components/headers/API-Version"
424440
}
425441
}
426442
}
427443
},
428444
"schemas": {
429-
"OASInput": {
445+
"OasInput": {
430446
"example": {
431447
"oasUrl": "oasUrl",
432448
"oasBody": "oasBody",
@@ -626,16 +642,17 @@
626642
"securitySchemes": {
627643
"apiKey": {
628644
"in": "header",
629-
"name": "X-API-Key",
630-
"type": "apiKey"
645+
"name": "X-Api-Key",
646+
"type": "apiKey",
647+
"description": "Read-only API keys for tools endpoints can be requested at https://apis.developer.overheid.nl/apis/key-aanvragen."
631648
},
632649
"clientCredentials": {
633650
"flows": {
634651
"clientCredentials": {
635652
"scopes": {
636-
"tools:read": "Toegang tot de tools endpoints"
653+
"tools": "Access to tools endpoints"
637654
},
638-
"tokenUrl": "https://auth.don.apps.digilab.network/realms/don/protocol/openid-connect/token"
655+
"tokenUrl": "https://auth.developer.overheid.nl/realms/don/protocol/openid-connect/token"
639656
}
640657
},
641658
"type": "oauth2"

0 commit comments

Comments
 (0)