описание основного апи

api-doc: уточнил формат created_at и др. date-range фильтров

See merge request hrbox-public/api!40

swagger.yml

@@ -0,0 +1,680 @@
+openapi: 3.0.3
+
+info:
+  title: HRBox API
+  version: 1.0.0
+  description: |
+    API для чтения подразделений, трудоустройств и пользователей.
+
+    Все методы требуют авторизованную сессию HRBox и соответствующее право доступа.
+    Ответ содержит массив `data` и метаданные пагинации `_meta`.
+
+servers:
+  - url: /api
+
+tags:
+  - name: department
+    description: Подразделения организационной структуры
+  - name: employment
+    description: Трудоустройства пользователей
+  - name: user
+    description: Пользователи
+
+paths:
+  /department:
+    get:
+      tags: [department]
+      summary: Получить список подразделений
+      operationId: getDepartments
+      description: Возвращает активные подразделения и организации.
+      x-permissions:
+        - show-structure-page
+      parameters:
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PerPage'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Fields'
+        - $ref: '#/components/parameters/Expand'
+        - name: id
+          in: query
+          description: ID подразделений через запятую
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: string
+              format: uuid
+        - name: name
+          in: query
+          description: Поиск по названию
+          schema:
+            type: string
+        - name: parent_id
+          in: query
+          description: ID родительского подразделения
+          schema:
+            type: string
+            format: uuid
+        - name: chief_id
+          in: query
+          description: ID руководителя
+          schema:
+            type: string
+            format: uuid
+        - name: is_organization
+          in: query
+          description: Признак организации
+          schema:
+            type: boolean
+        - name: is_null_parent_id
+          in: query
+          description: Только корневые подразделения
+          schema:
+            type: boolean
+        - name: status_id
+          in: query
+          description: Статусы подразделений через запятую
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: integer
+        - name: chief_only
+          in: query
+          description: Только подразделения текущего руководителя
+          schema:
+            type: boolean
+        - name: for_boss
+          in: query
+          description: Только управляемые текущим пользователем поддеревья
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Список подразделений
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/PaginatedResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/Department'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+  /employment:
+    get:
+      tags: [employment]
+      summary: Получить список трудоустройств
+      operationId: getEmployments
+      x-permissions:
+        - user-edit
+      parameters:
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PerPage'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Fields'
+        - $ref: '#/components/parameters/Expand'
+        - name: id
+          in: query
+          description: ID трудоустройства
+          schema:
+            type: string
+            format: uuid
+        - name: user_id
+          in: query
+          description: ID пользователя
+          schema:
+            type: string
+            format: uuid
+        - name: department_id
+          in: query
+          description: ID подразделения; учитывается его поддерево
+          schema:
+            type: string
+            format: uuid
+        - name: chief_id
+          in: query
+          description: ID трудоустройства руководителя
+          schema:
+            type: string
+            format: uuid
+        - name: position
+          in: query
+          description: Поиск по должности
+          schema:
+            type: string
+        - name: is_main
+          in: query
+          description: Только основное трудоустройство
+          schema:
+            type: boolean
+        - name: status_id
+          in: query
+          description: Статус трудоустройства
+          schema:
+            type: integer
+        - name: org_num
+          in: query
+          description: Табельные номера через запятую
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: string
+        - name: created_at
+          in: query
+          description: Дата или диапазон дат создания в формате `from|to`
+          schema:
+            type: string
+        - name: first_name
+          in: query
+          description: Поиск по имени
+          schema:
+            type: string
+        - name: last_name
+          in: query
+          description: Поиск по фамилии
+          schema:
+            type: string
+        - name: name
+          in: query
+          description: Поиск по имени и фамилии пользователя
+          schema:
+            type: string
+        - name: employment_date
+          in: query
+          description: Дата трудоустройства
+          schema:
+            type: string
+            format: date
+        - name: fired_date
+          in: query
+          description: Дата увольнения
+          schema:
+            type: string
+            format: date
+        - name: origin_id
+          in: query
+          description: Внешние ID через запятую
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: string
+        - name: origin_organization_id
+          in: query
+          description: Внешний ID организации
+          schema:
+            type: string
+        - name: reg_status_id
+          in: query
+          description: Регистрационные статусы пользователей через запятую
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: integer
+        - name: user_list_key
+          in: query
+          description: Ключ сохранённого списка пользователей
+          schema:
+            type: string
+            format: uuid
+        - name: chief_only
+          in: query
+          description: Текущий пользователь и его прямые подчинённые
+          schema:
+            type: boolean
+        - name: chief_only_all
+          in: query
+          description: Текущий пользователь и все его подчинённые
+          schema:
+            type: boolean
+        - name: multipleEmployment
+          in: query
+          description: Фильтр по наличию нескольких трудоустройств
+          schema:
+            type: boolean
+        - name: searchInAllSubDepartments
+          in: query
+          description: Искать во всех вложенных подразделениях
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Список трудоустройств
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/PaginatedResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/Employment'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+  /user:
+    get:
+      tags: [user]
+      summary: Получить список пользователей
+      operationId: getUsers
+      x-permissions:
+        anyOf:
+          - user-list
+          - show-user-page
+          - user-invite
+          - authenticated user with reports
+      parameters:
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PerPage'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Fields'
+        - $ref: '#/components/parameters/Expand'
+        - name: searchQuery
+          in: query
+          description: Сквозной полнотекстовый поиск пользователей
+          schema:
+            type: string
+        - name: q
+          in: query
+          description: Поиск по имени
+          schema:
+            type: string
+        - name: id
+          in: query
+          description: ID пользователей через запятую
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: string
+              format: uuid
+        - name: not_id
+          in: query
+          description: Исключить пользователя по ID
+          schema:
+            type: string
+            format: uuid
+        - name: email
+          in: query
+          description: Поиск по электронной почте
+          schema:
+            type: string
+        - name: phone_auth
+          in: query
+          description: Поиск по телефону авторизации
+          schema:
+            type: string
+        - name: name
+          in: query
+          description: Поиск по имени, фамилии и отчеству
+          schema:
+            type: string
+        - name: first_name
+          in: query
+          description: Поиск по имени
+          schema:
+            type: string
+        - name: middle_name
+          in: query
+          description: Поиск по отчеству
+          schema:
+            type: string
+        - name: last_name
+          in: query
+          description: Поиск по фамилии
+          schema:
+            type: string
+        - name: department_id
+          in: query
+          description: ID подразделения; учитывается его поддерево
+          schema:
+            type: string
+            format: uuid
+        - name: chief_id
+          in: query
+          description: ID руководителя
+          schema:
+            type: string
+            format: uuid
+        - name: position
+          in: query
+          description: Поиск по должности
+          schema:
+            type: string
+        - name: is_external
+          in: query
+          description: Признак внешнего пользователя
+          schema:
+            type: boolean
+        - name: reg_status_id
+          in: query
+          description: Регистрационные статусы через запятую
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: integer
+        - name: gender_id
+          in: query
+          description: Пол пользователя; несколько значений через запятую
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: integer
+        - name: duty_id
+          in: query
+          description: ID внутренней услуги
+          schema:
+            type: string
+            format: uuid
+        - name: birthday_date
+          in: query
+          description: Дата или диапазон дат рождения
+          schema:
+            type: string
+        - name: created_at
+          in: query
+          description: Дата или диапазон дат создания в формате `from|to`
+          schema:
+            type: string
+        - name: updated_at
+          in: query
+          description: Дата или диапазон дат изменения
+          schema:
+            type: string
+        - name: employment_date
+          in: query
+          description: Дата или диапазон дат трудоустройства
+          schema:
+            type: string
+        - name: is_boss
+          in: query
+          description: Признак руководителя
+          schema:
+            type: boolean
+        - name: group_id
+          in: query
+          description: ID группы пользователей
+          schema:
+            type: string
+            format: uuid
+        - name: status
+          in: query
+          description: ID персональных статусов через запятую
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: string
+              format: uuid
+        - name: survey_id
+          in: query
+          description: ID опроса
+          schema:
+            type: string
+            format: uuid
+        - name: survey_360_matrix_is_approved
+          in: query
+          description: Статус согласования матрицы 360
+          schema:
+            type: boolean
+        - name: company
+          in: query
+          description: Поиск по компании
+          schema:
+            type: string
+        - name: spec_id
+          in: query
+          description: ID профессиональной области
+          schema:
+            type: string
+            format: uuid
+        - name: chief_only
+          in: query
+          description: Текущий пользователь и его прямые подчинённые
+          schema:
+            type: boolean
+        - name: chief_only_all
+          in: query
+          description: Текущий пользователь и все его подчинённые
+          schema:
+            type: boolean
+        - name: user_list_key
+          in: query
+          description: Ключ сохранённого списка пользователей
+          schema:
+            type: string
+            format: uuid
+        - name: withoutEmployment
+          in: query
+          description: Только пользователи без трудоустройств
+          schema:
+            type: boolean
+        - name: searchInAllSubDepartments
+          in: query
+          description: Искать во всех вложенных подразделениях
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Список пользователей
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/PaginatedResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/User'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+components:
+  parameters:
+    Page:
+      name: page
+      in: query
+      description: Номер страницы, начиная с 1
+      schema:
+        type: integer
+        minimum: 1
+        default: 1
+    PerPage:
+      name: per-page
+      in: query
+      description: Количество элементов на странице
+      schema:
+        type: integer
+        minimum: 1
+        default: 20
+    Sort:
+      name: sort
+      in: query
+      description: Поля сортировки через запятую; префикс `-` задаёт сортировку по убыванию
+      schema:
+        type: string
+    Fields:
+      name: fields
+      in: query
+      description: Возвращаемые поля через запятую
+      schema:
+        type: string
+    Expand:
+      name: expand
+      in: query
+      description: Дополнительные связанные данные через запятую
+      schema:
+        type: string
+
+  responses:
+    Unauthorized:
+      description: Пользователь не авторизован
+    Forbidden:
+      description: Недостаточно прав
+
+  schemas:
+    PaginatedResponse:
+      type: object
+      required: [data, _meta]
+      properties:
+        data:
+          type: array
+          items: {}
+        _meta:
+          $ref: '#/components/schemas/PaginationMeta'
+
+    PaginationMeta:
+      type: object
+      required: [totalCount, pageCount, currentPage, perPage]
+      properties:
+        totalCount:
+          type: integer
+          example: 42
+        pageCount:
+          type: integer
+          example: 3
+        currentPage:
+          type: integer
+          example: 1
+        perPage:
+          type: integer
+          example: 20
+
+    Department:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        description:
+          type: string
+          nullable: true
+        parent_id:
+          type: string
+          format: uuid
+          nullable: true
+        chief_id:
+          type: string
+          format: uuid
+          nullable: true
+        is_organization:
+          type: boolean
+        status_id:
+          type: integer
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    Employment:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        user_id:
+          type: string
+          format: uuid
+        department_id:
+          type: string
+          format: uuid
+          nullable: true
+        chief_id:
+          type: string
+          format: uuid
+          nullable: true
+        position:
+          type: string
+          nullable: true
+        is_main:
+          type: boolean
+        employment_date:
+          type: string
+          format: date
+          nullable: true
+        fired_date:
+          type: string
+          format: date
+          nullable: true
+        status_id:
+          type: integer
+        org_num:
+          type: string
+          nullable: true
+
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        first_name:
+          type: string
+        middle_name:
+          type: string
+          nullable: true
+        last_name:
+          type: string
+        name:
+          type: string
+        birthday_date:
+          type: string
+          format: date
+          nullable: true
+        reg_status_id:
+          type: integer
+        gender_id:
+          type: integer
+          nullable: true
+        city_id:
+          type: string
+          format: uuid
+          nullable: true
+        company:
+          type: string
+          nullable: true
+        is_external:
+          type: boolean
+        photo_file_id:
+          type: string
+          format: uuid
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time