· 6 years ago · Feb 07, 2020, 01:32 PM
1swagger: '2.0'
2info:
3 description: Jarvis API
4 version: 1.0.0
5 title: Jarvis API
6host: jarvis.surfstudio.ru
7basePath: /api/v1
8schemes:
9- http
10
11paths:
12 /message/:
13 post:
14 summary: Отправка сообщения пользователю в slack
15 description: Можно использовать в скриптах для персонального уведомления
16 produces:
17 - application/json
18 parameters:
19 - in: body
20 name: message
21 required: true
22 schema:
23 $ref: '#/definitions/Message'
24 responses:
25 204:
26 description: Сообщение отправлено (или отправлена celery task)
27 404:
28 description: Пользователя с указанным id не существует
29 schema:
30 $ref: '#/definitions/HipchatError'
31 400:
32 description: Невалидные данные
33 schema:
34 $ref: '#/definitions/ValidationError'
35 /notification/:
36 post:
37 summary: отправка уведомления в группу Hipchat
38 description: Используется для уведомления в группы проектов (i.e. через Jenkins)
39 produces:
40 - application/json
41 parameters:
42 - in: body
43 name: message
44 required: true
45 schema:
46 $ref: '#/definitions/Notification'
47 responses:
48 204:
49 description: Сообщение отправлено (или отправлена celery task)
50 404:
51 description: Пользователя с указанным id не существует
52 schema:
53 $ref: '#/definitions/HipchatError'
54 /repositories/branches/default/:
55 get:
56 summary: получить мастер ветку
57 description:
58 Получить по URL мастер ветку в репозитории
59 parameters:
60 - name: repo_url
61 in: query
62 type: string
63 required: true
64 description: URL на репозиторий
65 responses:
66 200:
67 description: Main branch
68 schema:
69 $ref: '#/definitions/MainBranch'
70 /webhooks/version/:
71 post:
72 description: Вебхук для создания версии в Jira и оповещения, так же переводит задачи из статуса feedback в approved
73 produces:
74 - application/json
75 parameters:
76 - in: body
77 name: body
78 required: true
79 schema:
80 $ref: '#/definitions/BuildStatusWebhookPayload'
81 responses:
82 202:
83 description: Сообщение отправлено (или отправлена celery task)
84 400:
85 description: Не указано поле result в build
86 schema:
87 $ref: '#/definitions/WebhookError'
88 /webhooks/start-sprint/:
89 post:
90 summary: Вебхук для уведомления о начале спринта
91 description: Передается параметр sprint_id, с помощью этого параметра выясняется, в какой канал нужно отправлять уведомление
92 produces:
93 - application/json
94 parameters:
95 - in: body
96 name: body
97 required: true
98 schema:
99 $ref: '#/definitions/StartSprintWebhookPayload'
100 responses:
101 202:
102 description: Сообщение отправлено (или отправлена celery task)
103
104 /webhooks/bitbucket/pr/change/:
105 post:
106 description: |
107 Проверяет, что задача, связанная с source-веткой PR имеет исполнителя и оценку. Если все нормально - дергает targetUrl с тем же телом, что пришло в запросе. Если нет - отклоняет PR и отправляет сообщение создателю PR в Slack.
108 parameters:
109 - in: query
110 name: targetUrl
111 type: string
112 required: false
113 description: Url, на который будет проксирован запрос в случае, если PR проверен успешно
114 responses:
115 202:
116 description: Обработка запущена
117 201:
118 description: Имя ветки не содержит id задачи
119 /webhooks/jira/create-branch/:
120 post:
121 summary: deprecated
122 description: |
123 Создает новую ветку в репозитории проекта с именем
124 'dev/sprint-{sprint_number} при создании спринта. Если спринт уже есть в базе
125 то обновляется только его имя.
126 parameters:
127 - in: query
128 name: user_id
129 type: string
130 required: true
131 description: Отправляется жирой
132 - in: body
133 name: body
134 required: true
135 schema:
136 $ref: '#/definitions/CreateBranchWebhookBody'
137 responses:
138 202:
139 description: Таска создана
140 /webhooks/gitlab/mr/event/:
141 post:
142 summary: Обработчик события Merge Request на стороне Gitlab.
143 description: |
144 Проверяет, что задача, связанная с source-веткой PR имеет исполнителя и оценку. Если все нормально - дергает targetUrl с тем же телом, что пришло в запросе. Если нет - отклоняет PR и отправляет сообщение создателю PR в Slack. Проверяет событие, в случае нового MR отправляет сообщение ревьюверу, при закрытии созданного отправляет сообщение автору.
145 security:
146 - SecurityToken: []
147 parameters:
148 - in: query
149 name: targetUrl
150 type: string
151 required: false
152 description: Url, на который будет проксирован запрос в случае, если PR проверен успешно
153 responses:
154 202:
155 description: Обработка запущена
156 204:
157 description: Не указан проверяющий у открытого MR
158 404:
159 description: Отсутствуют данные или ветки не отличаются
160 /issues/change-status/:
161 post:
162 summary: Изменить статус у задачи
163 description: Изменение статуса у задачи в Jira
164 parameters:
165 - in: body
166 name: body
167 required: true
168 schema:
169 $ref: '#/definitions/ChangeTaskStatusRequest'
170 responses:
171 204:
172 description: OK
173 404:
174 description: Подходящий transition для
175 перемещения задачи не найден
176 schema:
177 type: object
178 properties:
179 message:
180 type: string
181 example: Suitable transition not found.
182 /report/preload_issues/:
183 get:
184 summary: загрузка данных для отчета
185 description: Перед тем как формировать остальные отчеты, нужно предварительно загрузить из jira и положить их в кэш
186 parameters:
187 - name: jql
188 type: string
189 required: true
190 in: query
191 description: jql запрос, во всех остальных запросах нужно подставлять этот jql
192 #example: 'project=test and sprint=2'
193 - name: enableCache
194 type: string
195 in: query
196 description: загузить новый кеш или использовать уже загруженные данные если они есть
197 #example: enableCache=yes|no
198 - name: authToken
199 type: string
200 required: false
201 in: query
202 description: токен для авторизации запроса, если пользователь авторизован в jarvis, токен не нужен
203 responses:
204 200:
205 description: successful operation
206 400:
207 description: Invalid status value
208 schema:
209 $ref: '#/definitions/ErrorMessage'
210 403:
211 description: Auth error
212
213 /report/preload_epics/:
214 get:
215 summary: предварительная загрузка данных для отчета
216 description: Перед тем как формировать остальные отчеты, нужно предварительно загрузить из jira и положить их в кеш, данный кеш нужен для отчетов по багам пользователя
217 parameters:
218 - name: jql
219 type: string
220 required: true
221 in: query
222 description: jql запрос, во всех остальных запросах нужно подставлять этот jql
223 #example: 'project=test and sprint=2'
224 - name: enableCache
225 type: string
226 in: query
227 description: загузить новый кеш или использовать уже загруженные данные если они есть
228 #example: enableCache=yes|no
229 - name: authToken
230 type: string
231 required: false
232 in: query
233 description: токен для атворизации запроса, если пользователь авторизован в jarvis, токен не нужен
234 responses:
235 200:
236 description: successful operation
237 400:
238 description: Invalid status value
239 schema:
240 $ref: '#/definitions/ErrorMessage'
241 403:
242 description: Auth error
243
244 /report/summary/:
245 get:
246 summary: сумарный отчет по задачам
247 description: форм
248 parameters:
249 - name: jql
250 type: string
251 required: true
252 in: query
253 description: jql запрос
254 #example: 'project=test and sprint=2'
255 - name: groupby
256 type: string
257 in: query
258 description: группировка отчета, может быть epics assignees sprints projects; example groupby=sprints
259 #example: ivanov
260 - name: query
261 type: string
262 in: query
263 description: дополнительные фильтры; example query=customfield_10008=="Документация"
264 required: false
265 - name: authToken
266 type: string
267 required: false
268 in: query
269 description: токен для авторизации запроса, если пользователь авторизован в jarvis, токен не нужен
270
271 responses:
272 200:
273 description: successful operation
274 schema:
275 $ref: '#/definitions/SummaryReport'
276 400:
277 description: Invalid status value
278 schema:
279 $ref: '#/definitions/ErrorMessage'
280 403:
281 description: Auth error
282
283 /report/overview/:
284 get:
285 summary: сумарный отчет по задачам
286 description: форм
287 parameters:
288 - name: jql
289 type: string
290 required: true
291 in: query
292 description: jql запрос
293 #example: 'project=test and sprint=2'
294 - name: groupby
295 type: string
296 in: query
297 description: группировка отчета, может быть epics assignees sprints projects; example groupby=sprints
298 #example: ivanov
299 required: false
300 - name: query
301 type: string
302 in: query
303 description: дополнительные фильтры; example query=customfield_10008=="Документация"
304 required: false
305 #example: ivanov
306 - name: authToken
307 type: string
308 required: false
309 in: query
310 description: токен для авторизации запроса, если пользователь авторизован в jarvis токен не нужен
311 responses:
312 200:
313 description: successful operation
314 schema:
315 $ref: '#/definitions/Overview'
316 400:
317 description: Invalid status value
318 schema:
319 $ref: '#/definitions/ErrorMessage'
320 403:
321 description: Auth error
322
323 /report/user_bug_info/:
324 get:
325 summary: запрос отчета
326 description: Баги пользователей
327 parameters:
328 - name: jql
329 type: string
330 required: true
331 in: query
332 description: jql запрос
333 #example: 'project=test and sprint=2'
334 - name: assigneename
335 type: string
336 in: query
337 description: исполнитель, example assigneename="ivanov,petrov"
338 #example: ivanov
339 - name: authToken
340 type: string
341 required: false
342 in: query
343 description: токен для атворизации запроса
344 responses:
345 200:
346 description: successful operation
347 schema:
348 $ref: '#/definitions/BugPesent'
349 400:
350 description: Invalid status value
351 schema:
352 $ref: '#/definitions/ErrorMessage'
353 403:
354 description: Auth error
355 /report/accuracy/:
356 get:
357 summary: запрос отчета
358 description: перед этим запросом нужно отправить запрос на заполнение кеша
359 parameters:
360 - name: jql
361 type: string
362 required: true
363 in: query
364 description: jql запрос
365 #example: 'project=test and sprint=2'
366 - name: groupby
367 type: string
368 in: query
369 description: сортировка
370 required: true
371 #example: assignees
372 - name: query
373 type: string
374 in: query
375 required: true
376 description: фильтр
377 #example: assigneename=="ivanov"
378 - name: authToken
379 type: string
380 required: false
381 in: query
382 description: токен для авторизации запроса
383 responses:
384 200:
385 description: successful operation
386 schema:
387 $ref: '#/definitions/Accuracy'
388 400:
389 description: Invalid status value
390 schema:
391 $ref: '#/definitions/ErrorMessage'
392 403:
393 description: Auth error
394
395 /report/bug_pesent/:
396 get:
397 summary: запрос отчета
398 description: Сколько багов сгенерировал разработчик
399 parameters:
400 - name: jql
401 type: string
402 required: true
403 in: query
404 description: jql запрос
405 - name: query
406 type: string
407 in: query
408 description: дополнительные фильтры; example query=customfield_10008=="Документация"
409 required: false
410 #example: ivanov
411 - name: groupby
412 type: string
413 in: query
414 description: группировка отчета, может быть epics assignees sprints projects; example groupby=sprints
415 #example: ivanov
416 required: false
417 - name: authToken
418 type: string
419 required: true
420 in: query
421 description: токен для авторизации запроса
422 responses:
423 200:
424 description: successful operation
425 schema:
426 $ref: '#/definitions/BugPesent'
427 400:
428 description: Invalid status value
429 schema:
430 $ref: '#/definitions/ErrorMessage'
431 403:
432 description: Auth error
433
434
435 /report/problems_issue/:
436 get:
437 summary: запрос отечета
438 description: Проблемные задачи
439 parameters:
440 - name: jql
441 type: string
442 required: true
443 in: query
444 description: jql запрос
445 - name: query
446 type: string
447 in: query
448 description: дополнительные фильтры; example query=customfield_10008=="Документация"
449 required: false
450 #example: ivanov
451 - name: authToken
452 type: string
453 required: true
454 in: query
455 description: токен для авторизации запроса
456 responses:
457 200:
458 description: successful operation
459 schema:
460 $ref: '#/definitions/ProblemIssues'
461 400:
462 description: Invalid status value
463 schema:
464 $ref: '#/definitions/ErrorMessage'
465 403:
466 description: Auth error
467
468 /analytics/buildinfo/:
469 get:
470 summary: получить статистику по build
471 parameters:
472 - name: authToken
473 type: string
474 required: true
475 in: query
476 description: токен для авторизации запроса
477 - name: post_stamp
478 type: string
479 required: false
480 in: query
481 description: указать точное время пример post_stamp=2019-05-01
482 - name: stamp_gte
483 type: string
484 required: false
485 in: query
486 description: дата вставки больше чем(включительно) пример stamp_gte=2019-05-01
487 - name: stamp_lte
488 type: string
489 required: false
490 in: query
491 description: дата вставки меньше чем(включительно) пример stamp_lte=2019-05-01
492 - name: id
493 type: number
494 required: false
495 in: query
496 description: id равно
497 - name: id_lte
498 type: number
499 required: false
500 in: query
501 description: id записи меньше чем(включительно)
502 - name: id_gte
503 type: number
504 required: false
505 in: query
506 description: id записи больше чем(включительно)
507 responses:
508 200:
509 description: successful operation
510 schema:
511 $ref: '#/definitions/ListBuildInfo'
512 post:
513 summary: вставить статистку
514 parameters:
515 - name: authToken
516 type: string
517 required: true
518 in: query
519 description: токен для авторизации запроса
520 - in: body
521 name: info
522 required: true
523 schema:
524 $ref: '#/definitions/BuildInfoPost'
525 responses:
526 200:
527 description: successful operation
528 schema:
529 $ref: '#/definitions/BuildInfo'
530 /jarvis/account/:
531 post:
532 summary: Создать новый аккаунт в базе Jarvis
533 parameters:
534 - name: body
535 in: body
536 schema:
537 $ref: '#/definitions/CreateAccountBody'
538 - name: authToken
539 type: string
540 in: query
541 required: true
542 description: Токен для авторизации запроса
543 responses:
544 201:
545 description: Пользователь создан
546 schema:
547 $ref: '#/definitions/CreateAccountResponse'
548 409:
549 description: Пользователь существует
550 schema:
551 $ref: '#/definitions/CreateAccountResponse'
552
553definitions:
554 CreateAccountResponse:
555 type: object
556 properties:
557 status:
558 type: string
559 data:
560 type: string
561
562 CreateAccountBody:
563 type: object
564 required:
565 - first_name
566 - last_name
567 - email
568 - jira_username
569 properties:
570 first_name:
571 type: string
572 last_name:
573 type: string
574 email:
575 type: string
576 jira_username:
577 type: string
578 bitbucket_username:
579 type: string
580 gitlab_username:
581 type: string
582 atlassian_id:
583 type: string
584 slack_user_id:
585 type: string
586
587 StartSprintWebhookPayload:
588 type: object
589 properties:
590 id:
591 type: integer
592 description: id спринта
593 name:
594 type: string
595 description: наименование спринта
596 end_date:
597 type: string
598 description: время окончания спринта
599
600 BuildInfo:
601 type: object
602 properties:
603 id:
604 type: number
605 description: id записи
606 postStamp:
607 description: время вставки записи
608 type: string
609 info:
610 type: object
611 description: информация по билду
612
613 BuildInfoPost:
614 type: object
615 properties:
616 info:
617 description: информация о Build в формате json
618 type: object
619
620 ListBuildInfo:
621 type: array
622 items:
623 $ref: '#/definitions/BuildInfo'
624
625 ProblemIssues:
626 description: Список проблемных задач, задачи, по которым неверно оценили время
627 type: array
628 items:
629 type: object
630 properties:
631 name:
632 type: string
633 val:
634 type: object
635 properties:
636 key:
637 description: идентификатор задачи
638 type: string
639 summary:
640 description: наименование задачи
641 type: string
642 estimation:
643 description: Предварительный расчет времени выполнения задачи
644 type: integer
645 accuracy:
646 description: Попадание в оценку(estimation/duration)
647 type: number
648 editRemaining:
649 description: Изменялось ли заложенное время
650 type: boolean
651 overtime:
652 description: флаг, с помощью которого можно определить, недооценнный или переоцененный
653 type: boolean
654 worklog:
655 type: array
656 description: Рабочая активность, список отметок исполнителей
657 items:
658 type: object
659 properties:
660 fullname:
661 description: Полное имя сотрудника
662 type: string
663 created:
664 description: Время создания комментария
665 type: string
666 timeSpent:
667 description: затреканное время
668 type: integer
669 comment:
670 description: комментарий к выполнению
671 type: string
672
673 SummaryReport:
674 description: Суммарный отчет по задачам
675 type: array
676 items:
677 type: object
678 properties:
679 name:
680 type: string
681 description: Значение, по которому формируется отчет (сотрудник, эпик, проект)
682 val:
683 type: object
684 description: значение отчета
685 properties:
686 max:
687 type: integer
688 description: максимальное значение в отчете,
689 либо сумма (timeBug, timeTask, timeServiceTask, remainingEstimate)
690 либо timeoriginalestimateTask
691 remainingEstimate:
692 type: integer
693 description: pass
694 timeBug:
695 type: integer
696 description: время, затраченное на баги
697 timeTask:
698 type: integer
699 description: время, затраченное на обычные таски
700 timeServiceTask:
701 type: integer
702 description: pass
703 timeoriginalestimateTask:
704 type: integer
705 description: pass
706
707 Overview:
708 description: Обзорный отчет по задач
709 type: array
710 items:
711 type: object
712 properties:
713 name:
714 type: string
715 description: Информация, по которой формируется отчет (эпик, проект, спринт, Задачи, Исполнители)
716 val:
717 type: object
718 description: pass
719 properties:
720 timeSpent:
721 type: integer
722 description: затреканное время
723
724 Accuracy:
725 description: Точность попадания в оценки
726 type: array
727 items:
728 type: object
729 properties:
730 name:
731 type: string
732 description: Информация, по которой формируется отчет (Эпик, проект, спринт, Задачи, Исполнители)
733 val:
734 type: object
735 description: pass
736 properties:
737 percent:
738 type: number
739 description: процент попадания в оценки
740
741 BugPesent:
742 description: Процент свой отладки
743 type: array
744 items:
745 type: object
746 properties:
747 name:
748 type: string
749 description: Информация, по которой формируется отчет(Эпик, проект, спринт, Задачи, Исполнители)
750 val:
751 type: object
752 description: pass
753 properties:
754 percent:
755 type: number
756 description: процент попадания в оценки
757
758
759 ErrorMessage:
760 type: object
761 properties:
762 status:
763 type: string
764 example: 'error'
765 message:
766 type: string
767 example: 'no valid jql'
768
769
770 Message:
771 description: уведомление сотрудников Surf, занеcенных в jarvis
772 type: object
773 required:
774 - message
775 - id_or_name
776 properties:
777 id_or_name:
778 type: string
779 example: jarvis@surfstudio.co
780 description: если id_type=bitbucket, то atlassian_id/bibucket_username, если id_type=email - то email
781 message:
782 type: string
783 example: Hello World
784 message_format:
785 type: string
786 example: text
787 description: Формат сообщения [html, text]
788 notify:
789 type: boolean
790 example: True
791 description: Должно ли это сообщение инициировать уведомление пользователя, не реализовано
792 id_type:
793 type: boolean
794 example: hipchat
795 description: Тип id, доступны [bitbucket, email]
796 as_task:
797 type: boolean
798 example: False
799 description: Обернуть запрос в celery task, True по-умолчанию, не реализованно
800
801 Notification:
802 type: object
803 required:
804 - message
805 - id_or_name
806 properties:
807 id_or_name:
808 type: string
809 example: jarvis@surfstudio.co
810 description: если id_type == bitbucket, в переменную нужно передавать адрес репозитория, если slack необходимо передать ID пользователя, hipchat id atlassian id
811 message:
812 type: string
813 example: Hello World
814 message_format:
815 type: string
816 example: text
817 description: Формат сообщения [html, text]
818 notify:
819 type: boolean
820 example: True
821 description: Должно ли это сообщение инициировать уведомление пользователя, не раелизовано
822 id_type:
823 type: string
824 example: bitbucket
825 description: Тип id, доступны [jira, bitbucket]
826 as_task:
827 type: boolean
828 example: False
829 description: Обернуть запрос в celery task, True по-умолчанию, не реализованно
830 sender:
831 type: string
832 example: Jarvis Server
833 description: не реализованно, подставить отправителя
834 color:
835 type: string
836 example: green
837 description: тип сообщения, default='gray', 'gray', 'purple', 'red', 'green', 'yellow', 'random'
838 ValidationError:
839 type: object
840 properties:
841 color:
842 type: array
843 items:
844 type: string
845 example: "'cyan' is not a valid color. Available colors ['yellow', 'purple', 'red', 'green', 'random', 'gray']"
846 message:
847 type: array
848 items:
849 type: string
850 example: This field is required
851 HipchatError:
852 type: object
853 properties:
854 error:
855 type: object
856 properties:
857 code:
858 type: number
859 example: 404
860 message:
861 type: string
862 example: Target user 25366005 is not a valid user
863 type:
864 type: string
865 example: Not found
866 BuildStatusWebhookPayload:
867 type: object
868 required:
869 - repo_url
870 - tag_name
871 - build
872 - ci_url
873 properties:
874 build:
875 type: object
876 properties:
877 job_name:
878 type: string
879 example: 3242
880 number:
881 type: number
882 example: 12
883 status:
884 type: string
885 example: FAILURE
886 stages_result:
887 type: array
888 items:
889 type: object
890 properties:
891 name:
892 type: string
893 example: linter
894 status:
895 type: string
896 example: SUCCESS
897 repo_url:
898 type: string
899 example: https://bitbucket.org/surfstudio/test-jira
900 ci_url:
901 type: string
902 example: http://jenkins.surfstudio.ru
903 tag_name:
904 type: string
905 example: 1.2.3-rc3
906 message:
907 type: string
908 example: Hello World
909 WebhookError:
910 type: object
911 properties:
912 result:
913 type: array
914 items:
915 type: string
916 example: This field is requred.
917 MainBranch:
918 type: object
919 properties:
920 name:
921 type: string
922 example: dev/sprint-1
923 ChangeTaskStatusRequest:
924 type: object
925 required:
926 - status_name
927 - issue_key
928 properties:
929 status_name:
930 type: string
931 example: In Progress
932 description: case insensetive поле
933 issue_key:
934 type: string
935 example: TEST-3
936 CreateBranchWebhookBody:
937 type: object
938 properties:
939 timestamp:
940 type: number
941 example: 1523641146036
942 webhook_event:
943 type: string
944 example: sprint_updated
945 sprint:
946 type: object
947 properties:
948 id:
949 type: integer
950 example: 58
951 self:
952 type: string
953 example: 'https://jira.surfstudio.ru/rest/agile/1.0/sprint/158'
954 state:
955 type: string
956 example: active
957 name:
958 type: string
959 example: JARVIS 23 CoolSprint
960 start_date:
961 type: string
962 example: '2018-04-11T18:15:56.434+03:00'
963 end_date:
964 type: string
965 example: '2018-04-25T18:15:00.000+03:00'
966 origin_board_id:
967 type: integer
968 example: 84
969 goal:
970 type: string
971 example: asd
972 old_value:
973 type: object
974 properties:
975 id:
976 type: integer
977 example: 158
978 self:
979 type: string
980 example: 'https://jira.surfstudio.ru/rest/agile/1.0/sprint/158'
981 state:
982 type: string
983 example: active
984 name:
985 type: string
986 example: '2333'
987 start_date:
988 type: string
989 example: '2018-04-11T18:15:56.434+03:00'
990 end_date:
991 type: string
992 example: '2018-04-25T18:15:00.000+03:00'
993 origin_board_id:
994 type: integer
995 example: 84
996 goal:
997 type: string
998 example: asd
999
1000securityDefinitions:
1001 SecurityToken:
1002 type: apiKey
1003 in: query
1004 name: authToken