@hexlet/frontend-blog-server 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,781 @@
1
+ openapi: 3.0.0
2
+ info:
3
+ title: Blog API
4
+ version: 1.0.0
5
+ description: 'Токен из POST /api/session или POST /api/users в заголовке Authorization: Bearer <token>.'
6
+ tags:
7
+ - name: System
8
+ - name: Users
9
+ - name: Session
10
+ - name: Categories
11
+ - name: Articles
12
+ paths:
13
+ /api/articles:
14
+ get:
15
+ operationId: Articles_list
16
+ description: Лента, новые статьи первыми.
17
+ parameters:
18
+ - name: page
19
+ in: query
20
+ required: false
21
+ schema:
22
+ type: integer
23
+ format: int32
24
+ default: 1
25
+ explode: false
26
+ - name: perPage
27
+ in: query
28
+ required: false
29
+ description: От 1 до 50.
30
+ schema:
31
+ type: integer
32
+ format: int32
33
+ default: 10
34
+ explode: false
35
+ - name: category
36
+ in: query
37
+ required: false
38
+ description: slug категории.
39
+ schema:
40
+ type: string
41
+ explode: false
42
+ - name: author
43
+ in: query
44
+ required: false
45
+ description: username автора.
46
+ schema:
47
+ type: string
48
+ explode: false
49
+ responses:
50
+ '200':
51
+ description: The request has succeeded.
52
+ content:
53
+ application/json:
54
+ schema:
55
+ $ref: '#/components/schemas/ArticlePage'
56
+ '400':
57
+ description: The server could not understand the request due to invalid syntax.
58
+ content:
59
+ application/json:
60
+ schema:
61
+ $ref: '#/components/schemas/ApiError'
62
+ tags:
63
+ - Articles
64
+ post:
65
+ operationId: Articles_create
66
+ parameters: []
67
+ responses:
68
+ '201':
69
+ description: The request has succeeded and a new resource has been created as a result.
70
+ content:
71
+ application/json:
72
+ schema:
73
+ $ref: '#/components/schemas/Article'
74
+ '400':
75
+ description: The server could not understand the request due to invalid syntax.
76
+ content:
77
+ application/json:
78
+ schema:
79
+ $ref: '#/components/schemas/ApiError'
80
+ '401':
81
+ description: Access is unauthorized.
82
+ content:
83
+ application/json:
84
+ schema:
85
+ $ref: '#/components/schemas/ApiError'
86
+ tags:
87
+ - Articles
88
+ requestBody:
89
+ required: true
90
+ content:
91
+ application/json:
92
+ schema:
93
+ $ref: '#/components/schemas/ArticleInput'
94
+ security:
95
+ - BearerAuth: []
96
+ /api/articles/{id}:
97
+ get:
98
+ operationId: Articles_read
99
+ description: С токеном поле liked показывает лайк текущего пользователя.
100
+ parameters:
101
+ - name: id
102
+ in: path
103
+ required: true
104
+ schema:
105
+ type: integer
106
+ format: int32
107
+ responses:
108
+ '200':
109
+ description: The request has succeeded.
110
+ content:
111
+ application/json:
112
+ schema:
113
+ $ref: '#/components/schemas/Article'
114
+ '404':
115
+ description: The server cannot find the requested resource.
116
+ content:
117
+ application/json:
118
+ schema:
119
+ $ref: '#/components/schemas/ApiError'
120
+ tags:
121
+ - Articles
122
+ security:
123
+ - BearerAuth: []
124
+ - {}
125
+ patch:
126
+ operationId: Articles_update
127
+ description: Правка. Доступна только автору.
128
+ parameters:
129
+ - name: id
130
+ in: path
131
+ required: true
132
+ schema:
133
+ type: integer
134
+ format: int32
135
+ responses:
136
+ '200':
137
+ description: The request has succeeded.
138
+ content:
139
+ application/json:
140
+ schema:
141
+ $ref: '#/components/schemas/Article'
142
+ '400':
143
+ description: The server could not understand the request due to invalid syntax.
144
+ content:
145
+ application/json:
146
+ schema:
147
+ $ref: '#/components/schemas/ApiError'
148
+ '401':
149
+ description: Access is unauthorized.
150
+ content:
151
+ application/json:
152
+ schema:
153
+ $ref: '#/components/schemas/ApiError'
154
+ '403':
155
+ description: Access is forbidden.
156
+ content:
157
+ application/json:
158
+ schema:
159
+ $ref: '#/components/schemas/ApiError'
160
+ '404':
161
+ description: The server cannot find the requested resource.
162
+ content:
163
+ application/json:
164
+ schema:
165
+ $ref: '#/components/schemas/ApiError'
166
+ tags:
167
+ - Articles
168
+ requestBody:
169
+ required: true
170
+ content:
171
+ application/json:
172
+ schema:
173
+ $ref: '#/components/schemas/ArticlePatch'
174
+ security:
175
+ - BearerAuth: []
176
+ delete:
177
+ operationId: Articles_remove
178
+ description: Удаление вместе с комментариями и лайками. Доступно только автору.
179
+ parameters:
180
+ - name: id
181
+ in: path
182
+ required: true
183
+ schema:
184
+ type: integer
185
+ format: int32
186
+ responses:
187
+ '204':
188
+ description: 'There is no content to send for this request, but the headers may be useful. '
189
+ '401':
190
+ description: Access is unauthorized.
191
+ content:
192
+ application/json:
193
+ schema:
194
+ $ref: '#/components/schemas/ApiError'
195
+ '403':
196
+ description: Access is forbidden.
197
+ content:
198
+ application/json:
199
+ schema:
200
+ $ref: '#/components/schemas/ApiError'
201
+ '404':
202
+ description: The server cannot find the requested resource.
203
+ content:
204
+ application/json:
205
+ schema:
206
+ $ref: '#/components/schemas/ApiError'
207
+ tags:
208
+ - Articles
209
+ security:
210
+ - BearerAuth: []
211
+ /api/articles/{id}/comments:
212
+ get:
213
+ operationId: Articles_comments
214
+ parameters:
215
+ - name: id
216
+ in: path
217
+ required: true
218
+ schema:
219
+ type: integer
220
+ format: int32
221
+ responses:
222
+ '200':
223
+ description: The request has succeeded.
224
+ content:
225
+ application/json:
226
+ schema:
227
+ type: array
228
+ items:
229
+ $ref: '#/components/schemas/Comment'
230
+ '404':
231
+ description: The server cannot find the requested resource.
232
+ content:
233
+ application/json:
234
+ schema:
235
+ $ref: '#/components/schemas/ApiError'
236
+ tags:
237
+ - Articles
238
+ post:
239
+ operationId: Articles_comment
240
+ parameters:
241
+ - name: id
242
+ in: path
243
+ required: true
244
+ schema:
245
+ type: integer
246
+ format: int32
247
+ responses:
248
+ '201':
249
+ description: The request has succeeded and a new resource has been created as a result.
250
+ content:
251
+ application/json:
252
+ schema:
253
+ $ref: '#/components/schemas/Comment'
254
+ '400':
255
+ description: The server could not understand the request due to invalid syntax.
256
+ content:
257
+ application/json:
258
+ schema:
259
+ $ref: '#/components/schemas/ApiError'
260
+ '401':
261
+ description: Access is unauthorized.
262
+ content:
263
+ application/json:
264
+ schema:
265
+ $ref: '#/components/schemas/ApiError'
266
+ '404':
267
+ description: The server cannot find the requested resource.
268
+ content:
269
+ application/json:
270
+ schema:
271
+ $ref: '#/components/schemas/ApiError'
272
+ tags:
273
+ - Articles
274
+ requestBody:
275
+ required: true
276
+ content:
277
+ application/json:
278
+ schema:
279
+ $ref: '#/components/schemas/CommentInput'
280
+ security:
281
+ - BearerAuth: []
282
+ /api/articles/{id}/like:
283
+ put:
284
+ operationId: Articles_like
285
+ description: Поставить лайк. Повторный вызов ничего не меняет.
286
+ parameters:
287
+ - name: id
288
+ in: path
289
+ required: true
290
+ schema:
291
+ type: integer
292
+ format: int32
293
+ responses:
294
+ '200':
295
+ description: The request has succeeded.
296
+ content:
297
+ application/json:
298
+ schema:
299
+ $ref: '#/components/schemas/LikeState'
300
+ '401':
301
+ description: Access is unauthorized.
302
+ content:
303
+ application/json:
304
+ schema:
305
+ $ref: '#/components/schemas/ApiError'
306
+ '404':
307
+ description: The server cannot find the requested resource.
308
+ content:
309
+ application/json:
310
+ schema:
311
+ $ref: '#/components/schemas/ApiError'
312
+ tags:
313
+ - Articles
314
+ security:
315
+ - BearerAuth: []
316
+ delete:
317
+ operationId: Articles_unlike
318
+ description: Снять лайк. Повторный вызов ничего не меняет.
319
+ parameters:
320
+ - name: id
321
+ in: path
322
+ required: true
323
+ schema:
324
+ type: integer
325
+ format: int32
326
+ responses:
327
+ '200':
328
+ description: The request has succeeded.
329
+ content:
330
+ application/json:
331
+ schema:
332
+ $ref: '#/components/schemas/LikeState'
333
+ '401':
334
+ description: Access is unauthorized.
335
+ content:
336
+ application/json:
337
+ schema:
338
+ $ref: '#/components/schemas/ApiError'
339
+ '404':
340
+ description: The server cannot find the requested resource.
341
+ content:
342
+ application/json:
343
+ schema:
344
+ $ref: '#/components/schemas/ApiError'
345
+ tags:
346
+ - Articles
347
+ security:
348
+ - BearerAuth: []
349
+ /api/categories:
350
+ get:
351
+ operationId: Categories_list
352
+ parameters: []
353
+ responses:
354
+ '200':
355
+ description: The request has succeeded.
356
+ content:
357
+ application/json:
358
+ schema:
359
+ type: array
360
+ items:
361
+ $ref: '#/components/schemas/Category'
362
+ tags:
363
+ - Categories
364
+ /api/health:
365
+ get:
366
+ operationId: Health_check
367
+ parameters: []
368
+ responses:
369
+ '200':
370
+ description: The request has succeeded.
371
+ content:
372
+ application/json:
373
+ schema:
374
+ type: object
375
+ properties:
376
+ status:
377
+ type: string
378
+ enum:
379
+ - ok
380
+ required:
381
+ - status
382
+ tags:
383
+ - System
384
+ /api/me:
385
+ get:
386
+ operationId: Me_me
387
+ description: Текущий пользователь по токену.
388
+ parameters: []
389
+ responses:
390
+ '200':
391
+ description: The request has succeeded.
392
+ content:
393
+ application/json:
394
+ schema:
395
+ $ref: '#/components/schemas/User'
396
+ '401':
397
+ description: Access is unauthorized.
398
+ content:
399
+ application/json:
400
+ schema:
401
+ $ref: '#/components/schemas/ApiError'
402
+ tags:
403
+ - Session
404
+ security:
405
+ - BearerAuth: []
406
+ /api/session:
407
+ post:
408
+ operationId: SessionRoutes_login
409
+ description: Вход.
410
+ parameters: []
411
+ responses:
412
+ '200':
413
+ description: The request has succeeded.
414
+ content:
415
+ application/json:
416
+ schema:
417
+ $ref: '#/components/schemas/Session'
418
+ '400':
419
+ description: The server could not understand the request due to invalid syntax.
420
+ content:
421
+ application/json:
422
+ schema:
423
+ $ref: '#/components/schemas/ApiError'
424
+ '401':
425
+ description: Access is unauthorized.
426
+ content:
427
+ application/json:
428
+ schema:
429
+ $ref: '#/components/schemas/ApiError'
430
+ tags:
431
+ - Session
432
+ requestBody:
433
+ required: true
434
+ content:
435
+ application/json:
436
+ schema:
437
+ $ref: '#/components/schemas/Credentials'
438
+ /api/users:
439
+ post:
440
+ operationId: Users_signup
441
+ description: Регистрация. Сразу возвращает сессию.
442
+ parameters: []
443
+ responses:
444
+ '201':
445
+ description: The request has succeeded and a new resource has been created as a result.
446
+ content:
447
+ application/json:
448
+ schema:
449
+ $ref: '#/components/schemas/Session'
450
+ '400':
451
+ description: The server could not understand the request due to invalid syntax.
452
+ content:
453
+ application/json:
454
+ schema:
455
+ $ref: '#/components/schemas/ApiError'
456
+ '409':
457
+ description: The request conflicts with the current state of the server.
458
+ content:
459
+ application/json:
460
+ schema:
461
+ $ref: '#/components/schemas/ApiError'
462
+ tags:
463
+ - Users
464
+ requestBody:
465
+ required: true
466
+ content:
467
+ application/json:
468
+ schema:
469
+ $ref: '#/components/schemas/Credentials'
470
+ /api/users/{username}:
471
+ get:
472
+ operationId: Users_profile
473
+ description: Профиль автора по имени.
474
+ parameters:
475
+ - name: username
476
+ in: path
477
+ required: true
478
+ schema:
479
+ type: string
480
+ responses:
481
+ '200':
482
+ description: The request has succeeded.
483
+ content:
484
+ application/json:
485
+ schema:
486
+ $ref: '#/components/schemas/Profile'
487
+ '404':
488
+ description: The server cannot find the requested resource.
489
+ content:
490
+ application/json:
491
+ schema:
492
+ $ref: '#/components/schemas/ApiError'
493
+ tags:
494
+ - Users
495
+ components:
496
+ schemas:
497
+ ApiError:
498
+ type: object
499
+ required:
500
+ - code
501
+ - message
502
+ properties:
503
+ code:
504
+ type: string
505
+ enum:
506
+ - validation_error
507
+ - unauthorized
508
+ - forbidden
509
+ - not_found
510
+ - username_taken
511
+ - invalid_credentials
512
+ message:
513
+ type: string
514
+ description: |-
515
+ Ошибка API. code — машинный код без текста на конкретном языке, сообщение для
516
+ пользователя фронтенд берёт из своих переводов по коду. message — подсказка
517
+ разработчику на английском.
518
+ example:
519
+ code: validation_error
520
+ message: title must not be empty
521
+ Article:
522
+ type: object
523
+ required:
524
+ - id
525
+ - title
526
+ - excerpt
527
+ - category
528
+ - author
529
+ - createdAt
530
+ - likesCount
531
+ - commentsCount
532
+ - body
533
+ - updatedAt
534
+ - liked
535
+ properties:
536
+ id:
537
+ type: integer
538
+ format: int32
539
+ title:
540
+ type: string
541
+ excerpt:
542
+ type: string
543
+ category:
544
+ $ref: '#/components/schemas/Category'
545
+ author:
546
+ $ref: '#/components/schemas/User'
547
+ createdAt:
548
+ type: string
549
+ format: date-time
550
+ likesCount:
551
+ type: integer
552
+ format: int32
553
+ commentsCount:
554
+ type: integer
555
+ format: int32
556
+ body:
557
+ type: string
558
+ updatedAt:
559
+ type: string
560
+ format: date-time
561
+ liked:
562
+ type: boolean
563
+ description: |-
564
+ Статья целиком. body — исходный Markdown, его рендерит фронтенд.
565
+ liked — поставил ли лайк текущий пользователь; для гостя всегда false.
566
+ ArticleInput:
567
+ type: object
568
+ required:
569
+ - title
570
+ - body
571
+ - categoryId
572
+ properties:
573
+ title:
574
+ type: string
575
+ body:
576
+ type: string
577
+ categoryId:
578
+ type: integer
579
+ format: int32
580
+ description: 'Данные для создания статьи. title: 1–120 символов, body: непустой.'
581
+ ArticlePage:
582
+ type: object
583
+ required:
584
+ - items
585
+ - page
586
+ - perPage
587
+ - total
588
+ properties:
589
+ items:
590
+ type: array
591
+ items:
592
+ $ref: '#/components/schemas/ArticleSummary'
593
+ page:
594
+ type: integer
595
+ format: int32
596
+ perPage:
597
+ type: integer
598
+ format: int32
599
+ total:
600
+ type: integer
601
+ format: int32
602
+ description: Страница ленты.
603
+ ArticlePatch:
604
+ type: object
605
+ properties:
606
+ title:
607
+ type: string
608
+ body:
609
+ type: string
610
+ categoryId:
611
+ type: integer
612
+ format: int32
613
+ description: 'Правка статьи: передаются только меняющиеся поля.'
614
+ ArticleSummary:
615
+ type: object
616
+ required:
617
+ - id
618
+ - title
619
+ - excerpt
620
+ - category
621
+ - author
622
+ - createdAt
623
+ - likesCount
624
+ - commentsCount
625
+ properties:
626
+ id:
627
+ type: integer
628
+ format: int32
629
+ title:
630
+ type: string
631
+ excerpt:
632
+ type: string
633
+ category:
634
+ $ref: '#/components/schemas/Category'
635
+ author:
636
+ $ref: '#/components/schemas/User'
637
+ createdAt:
638
+ type: string
639
+ format: date-time
640
+ likesCount:
641
+ type: integer
642
+ format: int32
643
+ commentsCount:
644
+ type: integer
645
+ format: int32
646
+ description: Статья в ленте. body в ленте не приходит, только excerpt — начало текста без разметки Markdown.
647
+ Category:
648
+ type: object
649
+ required:
650
+ - id
651
+ - slug
652
+ - name
653
+ properties:
654
+ id:
655
+ type: integer
656
+ format: int32
657
+ slug:
658
+ type: string
659
+ name:
660
+ type: string
661
+ description: |-
662
+ Категория. Список статический и задаётся сидом. slug стабилен и годится для URL и
663
+ ключей перевода, name — название по-английски.
664
+ example:
665
+ id: 1
666
+ slug: frontend
667
+ name: Frontend
668
+ Comment:
669
+ type: object
670
+ required:
671
+ - id
672
+ - body
673
+ - parentId
674
+ - author
675
+ - createdAt
676
+ properties:
677
+ id:
678
+ type: integer
679
+ format: int32
680
+ body:
681
+ type: string
682
+ parentId:
683
+ type: integer
684
+ format: int32
685
+ nullable: true
686
+ author:
687
+ $ref: '#/components/schemas/User'
688
+ createdAt:
689
+ type: string
690
+ format: date-time
691
+ description: |-
692
+ Комментарий. Список приходит плоским, по возрастанию createdAt; дерево фронтенд
693
+ собирает сам по parentId. parentId = null у ответа на саму статью.
694
+ CommentInput:
695
+ type: object
696
+ required:
697
+ - body
698
+ properties:
699
+ body:
700
+ type: string
701
+ parentId:
702
+ type: integer
703
+ format: int32
704
+ nullable: true
705
+ description: Новый комментарий. parentId — комментарий той же статьи, на который это ответ.
706
+ Credentials:
707
+ type: object
708
+ required:
709
+ - username
710
+ - password
711
+ properties:
712
+ username:
713
+ type: string
714
+ password:
715
+ type: string
716
+ description: 'Логин и пароль. username: 3–20 символов из латиницы, цифр, _ и -; password: от 6 символов.'
717
+ example:
718
+ username: alice
719
+ password: password
720
+ LikeState:
721
+ type: object
722
+ required:
723
+ - liked
724
+ - likesCount
725
+ properties:
726
+ liked:
727
+ type: boolean
728
+ likesCount:
729
+ type: integer
730
+ format: int32
731
+ description: Состояние лайка после изменения.
732
+ Profile:
733
+ type: object
734
+ required:
735
+ - id
736
+ - username
737
+ - articlesCount
738
+ properties:
739
+ id:
740
+ type: integer
741
+ format: int32
742
+ username:
743
+ type: string
744
+ articlesCount:
745
+ type: integer
746
+ format: int32
747
+ description: Профиль автора.
748
+ Session:
749
+ type: object
750
+ required:
751
+ - token
752
+ - user
753
+ properties:
754
+ token:
755
+ type: string
756
+ user:
757
+ $ref: '#/components/schemas/User'
758
+ description: 'Ответ на вход и регистрацию. token передаётся в заголовке Authorization: Bearer <token>.'
759
+ User:
760
+ type: object
761
+ required:
762
+ - id
763
+ - username
764
+ properties:
765
+ id:
766
+ type: integer
767
+ format: int32
768
+ username:
769
+ type: string
770
+ description: Публичные данные пользователя.
771
+ example:
772
+ id: 1
773
+ username: alice
774
+ securitySchemes:
775
+ BearerAuth:
776
+ type: http
777
+ scheme: Bearer
778
+ servers:
779
+ - url: http://localhost:8080
780
+ description: Local development
781
+ variables: {}