Skip to content

Commit af66118

Browse files
jmgasperjmgasper
committed
Swagger updates for QA
1 parent 5f7e45b commit af66118

File tree

2 files changed

+158
-40
lines changed

2 files changed

+158
-40
lines changed

‎app.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ const resourcesAPISwaggerDoc = YAML.load('./docs/swagger.yaml')
1919
// setup express app
2020
const app = express()
2121

22-
// serve resources V5 API swagger definition
22+
// serve resources V6 API swagger definition
2323
app.use('/v6/resources/api-docs', swaggerUi.serve, swaggerUi.setup(resourcesAPISwaggerDoc))
2424

2525
app.use(cors({

‎docs/swagger.yaml‎

Lines changed: 157 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,25 @@
11
swagger: '2.0'
22
info:
3-
title: V5 Challenge Resource API
4-
description: >
5-
## Security constraints
3+
title: V6 Challenge Resource API
4+
description: |
5+
## Overview
6+
The Challenge Resource API v6 manages challenge resource assignments, resource roles,
7+
and their phase dependencies. Use these endpoints to look up or manage the members
8+
attached to a challenge and to maintain the metadata that controls resource behavior.
69
10+
## Authentication
11+
Each endpoint description calls out the requirements for two supported token types:
712
8-
GET/POST/DELETE `/Resources` endpoints can only be called from admins, via
9-
M2M, or users for whom there is at least one existing `Resource` where
10-
`role.fullReadAccess`, `role.fullWriteAccess` and `role.isActive` are `true`.
11-
Special Case: User can create/delte selfObtainable resource for its own.
13+
- **JWT (user) tokens**: Accepted Topcoder roles are listed for every operation. A
14+
request succeeds only when the authenticated user's roles include one of those
15+
values.
16+
- **M2M (machine) tokens**: Supply the scopes identified for the operation. Scopes
17+
configured by default are `read:resources`, `create:resources`, `update:resources`,
18+
`delete:resources`, and `all:resources`.
1219
13-
`Resource Roles` POST and PUT endpoints can only be called from admins or
14-
via M2M.
15-
16-
GET `/Resources/{memberId}/challenges` endpoints can be called from any
17-
authenticated user or via M2M.
18-
19-
Resource role phase dependencies APIs can only be called from admins or M2M
20-
with valid scopes.
21-
version: 1.0.0
20+
Unless otherwise noted, endpoints expect an `Authorization: Bearer <token>` header.
21+
All routes are served under the `/v6` base path.
22+
version: 6.0.0
2223
host: api.topcoder.com
2324
securityDefinitions:
2425
Bearer:
@@ -28,15 +29,19 @@ securityDefinitions:
2829
schemes:
2930
- http
3031
- https
31-
basePath: /v5
32+
basePath: /v6
3233
produces:
3334
- application/json
3435
consumes:
3536
- application/json
3637
paths:
37-
/health:
38+
/resources/health:
3839
get:
39-
description: Health check endpoint
40+
description: |
41+
Returns a lightweight health summary that can be used for monitoring.
42+
43+
### Authentication
44+
- Not required.
4045
tags:
4146
- Health
4247
responses:
@@ -52,7 +57,13 @@ paths:
5257
$ref: '#/definitions/ServiceUnavailable'
5358
/resources:
5459
get:
55-
description: Get all resources for a challenge
60+
description: |
61+
Retrieve resources assigned to a challenge with optional filtering and sorting.
62+
63+
### Authentication
64+
- JWT roles: `administrator`, `copilot`, `Connect Manager`, `Topcoder User`
65+
- M2M scopes: `read:resources`, `all:resources`
66+
- Notes: Authentication is optional, but any supplied token must meet these requirements.
5667
tags:
5768
- Resources
5869
security:
@@ -108,9 +119,13 @@ paths:
108119
'500':
109120
$ref: '#/definitions/ServerError'
110121
post:
111-
description: >-
122+
description: |
112123
Create a new resource for a challenge. Verify that the challenge exists
113-
by calling the **/v5/challenges/{id}** endpoint using an M2M token.
124+
by calling the **/v6/challenges/{id}** endpoint using an M2M token.
125+
126+
### Authentication
127+
- JWT roles: `administrator`, `copilot`, `Connect Manager`, `Topcoder User`
128+
- M2M scopes: `create:resources`, `all:resources`
114129
tags:
115130
- Resources
116131
security:
@@ -139,7 +154,12 @@ paths:
139154
'500':
140155
$ref: '#/definitions/ServerError'
141156
delete:
142-
description: Delete a resource from a challenge
157+
description: |
158+
Delete a resource from a challenge.
159+
160+
### Authentication
161+
- JWT roles: `administrator`, `copilot`, `Connect Manager`, `Topcoder User`
162+
- M2M scopes: `delete:resources`, `all:resources`
143163
tags:
144164
- Resources
145165
security:
@@ -165,9 +185,78 @@ paths:
165185
$ref: '#/definitions/NotFound'
166186
'500':
167187
$ref: '#/definitions/ServerError'
188+
/resources/count:
189+
get:
190+
description: |
191+
Return the number of resources assigned to a challenge, optionally filtered by role.
192+
193+
### Authentication
194+
- JWT roles: `administrator`
195+
- M2M scopes: `read:resources`, `all:resources`
196+
tags:
197+
- Resources
198+
security:
199+
- Bearer: []
200+
parameters:
201+
- name: challengeId
202+
type: string
203+
description: The challenge id to inspect.
204+
format: UUID
205+
in: query
206+
required: true
207+
- name: roleId
208+
type: string
209+
description: Optional resource role id filter.
210+
format: UUID
211+
in: query
212+
responses:
213+
'200':
214+
description: OK - the request was successful
215+
schema:
216+
type: object
217+
properties:
218+
count:
219+
type: integer
220+
description: Number of matching resources.
221+
'400':
222+
$ref: '#/definitions/BadRequest'
223+
'401':
224+
$ref: '#/definitions/Unauthorized'
225+
'403':
226+
$ref: '#/definitions/Forbidden'
227+
'404':
228+
$ref: '#/definitions/NotFound'
229+
'500':
230+
$ref: '#/definitions/ServerError'
231+
/resources/internal/jobs/clean:
232+
post:
233+
description: |
234+
Remove non-production resource data created during automated testing.
235+
236+
### Authentication
237+
- JWT roles: `administrator`
238+
- M2M scopes: `all:resources`
239+
tags:
240+
- Resources
241+
security:
242+
- Bearer: []
243+
responses:
244+
'200':
245+
description: OK - the cleanup request succeeded
246+
'401':
247+
$ref: '#/definitions/Unauthorized'
248+
'403':
249+
$ref: '#/definitions/Forbidden'
250+
'500':
251+
$ref: '#/definitions/ServerError'
168252
'/resources/{memberId}/challenges':
169253
get:
170-
description: List all challenges that given topcoder member has access to.
254+
description: |
255+
List the challenge IDs that the specified Topcoder member currently has access to.
256+
257+
### Authentication
258+
- JWT roles: `administrator`, `copilot`, `Connect Manager`, `Topcoder User`
259+
- M2M scopes: `read:resources`, `all:resources`
171260
tags:
172261
- Resources
173262
security:
@@ -204,13 +293,13 @@ paths:
204293
$ref: '#/definitions/ServerError'
205294
/resource-roles:
206295
get:
207-
description: >-
208-
Get all resource roles. If isActive parameter is provided, filter the
209-
results by the set properties.
296+
description: |
297+
Get all resource roles. If filter parameters are provided, the results reflect those values.
298+
299+
### Authentication
300+
- Not required.
210301
tags:
211302
- Resource Roles
212-
security:
213-
- Bearer: []
214303
parameters:
215304
- name: isActive
216305
type: boolean
@@ -228,10 +317,14 @@ paths:
228317
type: boolean
229318
in: query
230319
description: Filters the results based on the `selfObtainable` property
231-
- name: fullAccess
320+
- name: fullReadAccess
321+
type: boolean
322+
in: query
323+
description: Filters the results based on the `fullReadAccess` property
324+
- name: fullWriteAccess
232325
type: boolean
233326
in: query
234-
description: Filters the results based on the `fullAccess` property
327+
description: Filters the results based on the `fullWriteAccess` property
235328
responses:
236329
'200':
237330
description: OK - the request was successful
@@ -250,7 +343,10 @@ paths:
250343
post:
251344
description: |
252345
Create a new resource role.
253-
Only admins can call this endpoint.
346+
347+
### Authentication
348+
- JWT roles: `administrator`
349+
- M2M scopes: `create:resources`, `all:resources`
254350
tags:
255351
- Resource Roles
256352
security:
@@ -280,7 +376,10 @@ paths:
280376
put:
281377
description: |
282378
Update an existing resource role.
283-
Only admins can call this endpoint.
379+
380+
### Authentication
381+
- JWT roles: `administrator`
382+
- M2M scopes: `update:resources`, `all:resources`
284383
tags:
285384
- Resource Roles
286385
security:
@@ -313,9 +412,14 @@ paths:
313412
$ref: '#/definitions/Conflict'
314413
'500':
315414
$ref: '#/definitions/ServerError'
316-
/resource-roles/Phase-dependencies:
415+
/resource-roles/phase-dependencies:
317416
get:
318-
description: Get resource role phase dependencies
417+
description: |
418+
Get resource role phase dependencies.
419+
420+
### Authentication
421+
- JWT roles: `administrator`
422+
- M2M scopes: `read:resources`, `all:resources`
319423
tags:
320424
- Resource Role Phase Dependencies
321425
security:
@@ -356,7 +460,12 @@ paths:
356460
'500':
357461
$ref: '#/definitions/ServerError'
358462
post:
359-
description: Create a new resource role phase dependency.
463+
description: |
464+
Create a new resource role phase dependency.
465+
466+
### Authentication
467+
- JWT roles: `administrator`
468+
- M2M scopes: `create:resources`, `all:resources`
360469
tags:
361470
- Resource Role Phase Dependencies
362471
security:
@@ -384,10 +493,14 @@ paths:
384493
$ref: '#/definitions/Conflict'
385494
'500':
386495
$ref: '#/definitions/ServerError'
387-
'/resource-roles/Phase-dependencies/{id}':
496+
'/resource-roles/phase-dependencies/{id}':
388497
put:
389498
description: |
390499
Update an existing resource role phase dependency.
500+
501+
### Authentication
502+
- JWT roles: `administrator`
503+
- M2M scopes: `update:resources`, `all:resources`
391504
tags:
392505
- Resource Role Phase Dependencies
393506
security:
@@ -422,7 +535,12 @@ paths:
422535
'500':
423536
$ref: '#/definitions/ServerError'
424537
delete:
425-
description: Delete a resource role phase dependency
538+
description: |
539+
Delete a resource role phase dependency.
540+
541+
### Authentication
542+
- JWT roles: `administrator`
543+
- M2M scopes: `delete:resources`, `all:resources`
426544
tags:
427545
- Resource Role Phase Dependencies
428546
security:
@@ -511,7 +629,7 @@ definitions:
511629
type: object
512630
required:
513631
- name
514-
- fullReadccess
632+
- fullReadAccess
515633
- fullWriteAccess
516634
- isActive
517635
- selfObtainable

0 commit comments

Comments
 (0)