Skip to content

Commit 817cbed

Browse files
jreynard-codejreynard-code
committed
Update Runner API documentation and streamline parameter references
- Revised API documentation with proper title, description, and version details. - Replaced inline parameter definitions with reusable components for `organizationId`, `workspaceId`, `runnerId`, `page`, and `size`. - Enhanced parameter descriptions with consistent formatting and capitalization. - Updated YAML structure to reference new parameter components across multiple endpoints.
1 parent 86f98f5 commit 817cbed

2 files changed

Lines changed: 72 additions & 172 deletions

File tree

‎doc/Apis/RunnerApi.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -280,8 +280,8 @@ List all Runners
280280
|------------- | ------------- | ------------- | -------------|
281281
| **organization\_id** | **String**| the Organization identifier | [default to null] |
282282
| **workspace\_id** | **String**| the Workspace identifier | [default to null] |
283-
| **page** | **Integer**| page number to query (first page is at index 0) | [optional] [default to null] |
284-
| **size** | **Integer**| amount of result by page | [optional] [default to null] |
283+
| **page** | **Integer**| Page number to query (first page is at index 0) | [optional] [default to null] |
284+
| **size** | **Integer**| Amount of result by page | [optional] [default to null] |
285285

286286
### Return type
287287

‎runner/src/main/openapi/runner.yaml‎

Lines changed: 70 additions & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
openapi: 3.0.3
22

33
info:
4-
title: ""
5-
version: ""
4+
title: Cosmo Tech Runner Manager API
5+
description: Cosmo Tech Runner Manager API
6+
version: 1.0.0-SNAPSHOT
7+
8+
servers:
9+
- url: 'http://localhost:8080'
610

711
security:
812
- oAuth2AuthCode: []
@@ -14,18 +18,8 @@ tags:
1418
paths:
1519
/organizations/{organization_id}/workspaces/{workspace_id}/runners:
1620
parameters:
17-
- name: organization_id
18-
in: path
19-
description: the Organization identifier
20-
required: true
21-
schema:
22-
type: string
23-
- name: workspace_id
24-
in: path
25-
description: the Workspace identifier
26-
required: true
27-
schema:
28-
type: string
21+
- $ref: '#/components/parameters/organizationId'
22+
- $ref: '#/components/parameters/workspaceId'
2923
post:
3024
operationId: createRunner
3125
tags:
@@ -72,18 +66,8 @@ paths:
7266
get:
7367
operationId: listRunners
7468
parameters:
75-
- name: page
76-
in: query
77-
description: page number to query (first page is at index 0)
78-
required: false
79-
schema:
80-
type: integer
81-
- name: size
82-
in: query
83-
description: amount of result by page
84-
required: false
85-
schema:
86-
type: integer
69+
- $ref: '#/components/parameters/page'
70+
- $ref: '#/components/parameters/size'
8771
tags:
8872
- runner
8973
summary: List all Runners
@@ -110,24 +94,9 @@ paths:
11094

11195
/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}:
11296
parameters:
113-
- name: organization_id
114-
in: path
115-
description: the Organization identifier
116-
required: true
117-
schema:
118-
type: string
119-
- name: workspace_id
120-
in: path
121-
description: the Workspace identifier
122-
required: true
123-
schema:
124-
type: string
125-
- name: runner_id
126-
in: path
127-
description: the Runner identifier
128-
required: true
129-
schema:
130-
type: string
97+
- $ref: '#/components/parameters/organizationId'
98+
- $ref: '#/components/parameters/workspaceId'
99+
- $ref: '#/components/parameters/runnerId'
131100
get:
132101
operationId: getRunner
133102
tags:
@@ -205,24 +174,9 @@ paths:
205174

206175
/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}/start:
207176
parameters:
208-
- name: organization_id
209-
in: path
210-
description: the Organization identifier
211-
required: true
212-
schema:
213-
type: string
214-
- name: workspace_id
215-
in: path
216-
description: the Workspace identifier
217-
required: true
218-
schema:
219-
type: string
220-
- name: runner_id
221-
in: path
222-
description: the Runner identifier
223-
required: true
224-
schema:
225-
type: string
177+
- $ref: '#/components/parameters/organizationId'
178+
- $ref: '#/components/parameters/workspaceId'
179+
- $ref: '#/components/parameters/runnerId'
226180
post:
227181
operationId: startRun
228182
tags:
@@ -243,24 +197,9 @@ paths:
243197

244198
/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}/stop:
245199
parameters:
246-
- name: organization_id
247-
in: path
248-
description: the Organization identifier
249-
required: true
250-
schema:
251-
type: string
252-
- name: workspace_id
253-
in: path
254-
description: the Workspace identifier
255-
required: true
256-
schema:
257-
type: string
258-
- name: runner_id
259-
in: path
260-
description: the Runner identifier
261-
required: true
262-
schema:
263-
type: string
200+
- $ref: '#/components/parameters/organizationId'
201+
- $ref: '#/components/parameters/workspaceId'
202+
- $ref: '#/components/parameters/runnerId'
264203
post:
265204
operationId: stopRun
266205
tags:
@@ -274,24 +213,9 @@ paths:
274213

275214
/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}/permissions/{role}:
276215
parameters:
277-
- name: organization_id
278-
in: path
279-
description: the Organization identifier
280-
required: true
281-
schema:
282-
type: string
283-
- name: workspace_id
284-
in: path
285-
description: the Workspace identifier
286-
required: true
287-
schema:
288-
type: string
289-
- name: runner_id
290-
in: path
291-
description: the Runner identifier
292-
required: true
293-
schema:
294-
type: string
216+
- $ref: '#/components/parameters/organizationId'
217+
- $ref: '#/components/parameters/workspaceId'
218+
- $ref: '#/components/parameters/runnerId'
295219
- name: role
296220
in: path
297221
description: the Role
@@ -326,24 +250,9 @@ paths:
326250

327251
/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}/security:
328252
parameters:
329-
- name: organization_id
330-
in: path
331-
description: the Organization identifier
332-
required: true
333-
schema:
334-
type: string
335-
- name: workspace_id
336-
in: path
337-
description: the Workspace identifier
338-
required: true
339-
schema:
340-
type: string
341-
- name: runner_id
342-
in: path
343-
description: the Runner identifier
344-
required: true
345-
schema:
346-
type: string
253+
- $ref: '#/components/parameters/organizationId'
254+
- $ref: '#/components/parameters/workspaceId'
255+
- $ref: '#/components/parameters/runnerId'
347256
get:
348257
operationId: getRunnerSecurity
349258
tags:
@@ -370,24 +279,9 @@ paths:
370279

371280
/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}/security/default:
372281
parameters:
373-
- name: organization_id
374-
in: path
375-
description: the Organization identifier
376-
required: true
377-
schema:
378-
type: string
379-
- name: workspace_id
380-
in: path
381-
description: the Workspace identifier
382-
required: true
383-
schema:
384-
type: string
385-
- name: runner_id
386-
in: path
387-
description: the Runner identifier
388-
required: true
389-
schema:
390-
type: string
282+
- $ref: '#/components/parameters/organizationId'
283+
- $ref: '#/components/parameters/workspaceId'
284+
- $ref: '#/components/parameters/runnerId'
391285
patch:
392286
operationId: updateRunnerDefaultSecurity
393287
tags:
@@ -436,24 +330,9 @@ paths:
436330

437331
/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}/security/access:
438332
parameters:
439-
- name: organization_id
440-
in: path
441-
description: the Organization identifier
442-
required: true
443-
schema:
444-
type: string
445-
- name: workspace_id
446-
in: path
447-
description: the Workspace identifier
448-
required: true
449-
schema:
450-
type: string
451-
- name: runner_id
452-
in: path
453-
description: the Runner identifier
454-
required: true
455-
schema:
456-
type: string
333+
- $ref: '#/components/parameters/organizationId'
334+
- $ref: '#/components/parameters/workspaceId'
335+
- $ref: '#/components/parameters/runnerId'
457336
post:
458337
operationId: createRunnerAccessControl
459338
tags:
@@ -496,24 +375,9 @@ paths:
496375

497376
/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}/security/access/{identity_id}:
498377
parameters:
499-
- name: organization_id
500-
in: path
501-
description: the Organization identifier
502-
required: true
503-
schema:
504-
type: string
505-
- name: workspace_id
506-
in: path
507-
description: the Workspace identifier
508-
required: true
509-
schema:
510-
type: string
511-
- name: runner_id
512-
in: path
513-
description: the Runner identifier
514-
required: true
515-
schema:
516-
type: string
378+
- $ref: '#/components/parameters/organizationId'
379+
- $ref: '#/components/parameters/workspaceId'
380+
- $ref: '#/components/parameters/runnerId'
517381
- name: identity_id
518382
in: path
519383
description: the User identifier
@@ -652,6 +516,42 @@ components:
652516
authorizationUrl: "https://example.com/authorize"
653517
tokenUrl: "https://example.com/token"
654518
scopes: {}
519+
parameters:
520+
organizationId:
521+
name: organization_id
522+
in: path
523+
description: the Organization identifier
524+
required: true
525+
schema:
526+
type: string
527+
workspaceId:
528+
name: workspace_id
529+
in: path
530+
description: the Workspace identifier
531+
required: true
532+
schema:
533+
type: string
534+
runnerId:
535+
name: runner_id
536+
in: path
537+
description: the Runner identifier
538+
required: true
539+
schema:
540+
type: string
541+
page:
542+
name: page
543+
in: query
544+
description: Page number to query (first page is at index 0)
545+
required: false
546+
schema:
547+
type: integer
548+
size:
549+
name: size
550+
in: query
551+
description: Amount of result by page
552+
required: false
553+
schema:
554+
type: integer
655555
schemas:
656556
# Base Runner object that includes all information
657557
Runner:

0 commit comments

Comments
 (0)