-
Notifications
You must be signed in to change notification settings - Fork 0
/
openapi_start.yml
444 lines (444 loc) · 13.1 KB
/
openapi_start.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
openapi: 3.0.3
info:
title: Marvel Universe API
version: 1.0.0
description: 'API for retrieving, creating, updating, and deleting information about the Marvel Universe.'
x-logo:
url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/7/71/Marvel-Comics-Logo.svg/1280px-Marvel-Comics-Logo.svg.png'
servers:
- url: 'http://localhost:3004/api'
description: Local
- url: 'http://localhost:3005'
description: Mock
- url: 'https://api-b6feef562ff3.deltablue.io/api'
description: Production
paths:
/characters:
get:
operationId: getCharacters
summary: Get all Marvel characters
description: Retrieve a list of all Marvel characters.
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CharactersResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
tags:
- Characters
post:
operationId: postCharacters
summary: Create a new Marvel character
description: Endpoint to create a new Marvel character.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MarvelCharacterModel'
example:
name: Rocket Raccoon
first_name: Rocket
last_name: Raccoon
description: A member of the Guardians of the Galaxy.
powers:
- Engineering genius
- Expert marksman
- Strategic thinking
responses:
'201':
description: Successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/MarvelCharacterModel'
'422':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
tags:
- Characters
'/characters/{id}':
get:
operationId: getCharacter
summary: Get a Marvel character
description: Retrieve information about a specific Marvel character.
parameters:
- $ref: '#/components/parameters/CharacterId'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/MarvelCharacterModel'
'404':
description: Marvel character not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
tags:
- Characters
put:
operationId: putCharacter
summary: Update a Marvel character
description: Update information about a specific Marvel character.
parameters:
- $ref: '#/components/parameters/CharacterId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MarvelCharacterModel'
example:
name: Rocket Raccoon
first_name: Rocket
last_name: Raccoon
description: A genetically modified raccoon with a knack for engineering and firearms. A member of the Guardians of the Galaxy.
powers:
- Engineering genius
- Expert marksman
- Strategic thinking
responses:
'200':
description: Successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/MarvelCharacterModel'
'404':
description: Marvel character not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'422':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
tags:
- Characters
delete:
operationId: deleteCharacter
summary: Delete a Marvel character
description: Delete a specific Marvel character.
parameters:
- $ref: '#/components/parameters/CharacterId'
responses:
'204':
description: Successfully deleted
'404':
description: Marvel character not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
tags:
- Characters
/teams:
get:
operationId: getCharacters # TODO
x-exclude: true
summary: Get all Marvel teams
description: Retrieve a list of all Marvel teams.
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/TeamsResponse'
# example:
tags:
- Teams
post:
operationId: postTeams
x-exclude: true
summary: Create a new Marvel team
description: Endpoint to create a new Marvel team.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MarvelTeamModel'
responses:
'201':
description: Successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/MarvelTeamModel'
'422':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
tags:
- Teams
'/teams/{id}':
get:
operationId: getCharacter
x-exclude: true
summary: Get a Marvel team
# description: Retrieve information about a specific Marvel team,
parameters:
- $ref: '#/components/parameters/TeamId'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/MarvelTeamModel'
'404':
description: Marvel team not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
tags:
- Teams
components:
parameters:
CharacterId:
name: id
in: path
required: true
description: ID of the Marvel character
schema:
type: integer
example: 1
TeamId:
name: id
in: path
required: true
description: ID of the Marvel team
schema:
type: integer
example: 1
LimitParam:
name: limit
in: query
description: The number of items to return per page.
required: false
schema:
type: integer
default: 10
maximum: 100
minimum: 1
PageParam:
name: page
in: query
description: The page number for pagination.
required: false
schema:
type: integer
default: 1
schemas:
MarvelCharacterModel:
description: A Marvel character.
type: object
properties:
id:
description: ID of the Marvel character
type: integer
format: int64
example: 7
readOnly: true
name:
description: The full name of the Marvel character.
type: string
example: Iron Man
first_name:
description: The first name of the Marvel character.
type: string
example: Tony
last_name:
description: The last name of the Marvel character.
type: string
example: Stark
description:
description: A brief description of the Marvel character.
type: string
example: 'Genius, billionaire, playboy, philanthropist.'
nullable: true
powers:
description: List of superpowers possessed by the Marvel character.
type: array
items:
type: string
example:
- Superhuman strength
- Powered armor suit
- Genius-level intellect
additionalProperties: false
required:
- name
MarvelTeamModel:
description: A Marvel team.
type: object
properties:
id:
description: ID of the Marvel team
type: integer
format: int64
example: ABC
readOnly: true
title:
description: The name of the Marvel team.
type: string
# example: Guardians of the Galaxy
description:
description: A brief description of the Marvel team.
type: string
# example: Interstellar heroes protecting the galaxy
nullable: true
additionalProperties: false
required:
- name
- description
CharactersResponse:
type: object
properties:
characters:
description: List of Marvel characters.
type: array
items:
$ref: '#/components/schemas/MarvelCharacterModel'
example:
characters:
- id: 1
name: Iron Man
first_name: Tony
last_name: Stark
description: 'Genius, billionaire, playboy, philanthropist.'
powers:
- Superhuman strength
- Powered armor suit
- Genius-level intellect
- id: 2
name: Spider-Man
first_name: Peter
last_name: Parker
description: Friendly neighborhood superhero.
powers:
- Wall-crawling
- Spider-sense
- Web-shooters
pagination:
$ref: '#/components/schemas/PaginationModel'
TeamsResponse:
type: object
properties:
teams:
description: List of Marvel teams.
type: array
items:
$ref: '#/components/schemas/MarvelTeamModel'
pagination:
$ref: '#/components/schemas/PaginationModel'
PaginationModel:
description: Pagination information.
type: object
properties:
pagination:
type: object
properties:
total:
description: The total number of items for the requested resource.
type: integer
example: 100
current_page:
description: The current page number.
type: integer
example: 1
next_page:
description: The next page number. Null if there is no next page.
type: integer
example: 2
nullable: true
prev_page:
description: The previous page number. Null if there is no previous page.
type: integer
example: null
nullable: true
per_page:
description: The number of items to return per page.
type: integer
example: 10
total_pages:
description: The total number of pages.
type: integer
example: 10
UnprocessableEntityError:
type: object
properties:
error:
description: Description of the error.
type: string
details:
description: An array of objects providing details about the validation errors encountered in the request.
type: array
items:
type: object
properties:
field:
description: The field causing the validation error.
type: string
message:
description: Details about the validation error.
type: string
example:
error: Validation errors
details:
- field: first_name
message: Field 'first_name' must be of type 'String'.
BadRequestError:
type: object
properties:
error:
description: Description of the error.
type: string
example:
error: Page number cannot be greater than total number of pages
NotFoundError:
type: object
properties:
error:
description: Description of the error.
type: string
example:
error: Marvel character not found
securitySchemes:
bearerAuth:
type: http
scheme: bearer
security:
- bearerAuth: []
tags:
- name: Characters
description: Manage all Marvel characters.
- name: Teams
description: Manage all teams from the Marvel Universe.
x-exclude: true