groups.yml

openapi: 3.0.3


paths:
  /groups:
    parameters:
      - $ref: './common.yml#/components/parameters/x-request'
    get:
      tags:
        - group
      summary: Get groups
      operationId: get_all_groups
      parameters:
        - $ref: './common.yml#/components/parameters/page'
        - $ref: './common.yml#/components/parameters/size'
      responses:
        200:
          description: "Successful operation, return all groups."
          content:
            application/json:
              schema:
                $ref: "./identification.yml#/components/schemas/GroupPage"
        400:
          $ref: "./common.yml#/components/responses/BadRequest"
    post:
      tags:
        - group
      summary: Create group
      operationId: create_group
      requestBody:
        description: "Request body for the group to create."
        required: true
        content:
          application/json:
            schema:
              $ref: "./identification.yml#/components/schemas/GroupToCreate"
      responses:
        201:
          $ref: "#/components/responses/SuccessGroup"
        400:
          $ref: "./common.yml#/components/responses/BadRequest"
  /groups/{groupId}:
    parameters:
      - $ref: '#/components/parameters/groupId'
      - $ref: './common.yml#/components/parameters/x-request'
    get:
      tags:
        - group
      summary: Get group
      operationId: get_group
      responses:
        200:
          $ref: "#/components/responses/SuccessGroup"
        400:
          $ref: "./common.yml#/components/responses/BadRequest"
        404:
          $ref: "#/components/responses/GroupNotFound"
    put:
      tags:
        - group
      summary: Update group
      operationId: update_group
      requestBody:
        description: "Request body for the group to update."
        required: true
        content:
          application/json:
            schema:
              $ref: "./identification.yml#/components/schemas/GroupToCreate"
      responses:
        204:
          $ref: "#/components/responses/SuccessEmpty"
        400:
          $ref: "./common.yml#/components/responses/BadRequest"
        404:
          $ref: "#/components/responses/GroupNotFound"
    delete:
      tags:
        - group
      summary: Delete group
      operationId: delete_group
      responses:
        204:
          $ref: "#/components/responses/SuccessEmpty"
        404:
          $ref: "#/components/responses/GroupNotFound"
  /groups/{groupId}/persons:
    parameters:
      - $ref: "#/components/parameters/groupId"
      - $ref: './common.yml#/components/parameters/x-request'
    get:
      tags:
        - group
      summary: Get group persons
      operationId: get_all_persons_by_group_id
      parameters:
        - $ref: './common.yml#/components/parameters/page'
        - $ref: './common.yml#/components/parameters/size'
      responses:
        '200':
          description: "Successful operation, return all persons."
          content:
            application/json:
              schema:
                $ref: "./identification.yml#/components/schemas/PersonsPage"
        '400':
          $ref: "./common.yml#/components/responses/BadRequest"
        '404':
          description: "Group with the groupId or persons with the personIds are not found."
          content:
            application/json:
              schema:
                $ref: "./common.yml#/components/schemas/OperationLog"
    put:
      tags:
        - group
      summary: Add/remove persons to group
      operationId: update_persons_in_group
      requestBody:
        description: "Request body for person IDs to add or remove."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/definitions/UpdateGroup"
      responses:
        204:
          $ref: "#/components/responses/SuccessEmpty"
        400:
          $ref: "./common.yml#/components/responses/BadRequest"
        404:
          $ref: "#/components/responses/GroupNotFound"

components:
  parameters:
    groupId:
      name: groupId
      in: path
      description: "Group ID."
      required: true
      schema:
        type: string
        format: uuid
  responses:
    SuccessEmpty:
      description: "Successful operation, return nothing."
    SuccessGroup:
      description: "Successful operation; return group."
      content:
        application/json:
          schema:
            $ref: "./identification.yml#/components/schemas/Group"
    GroupNotFound:
      description: "Group with the groupId is not found."
      content:
        application/json:
          schema:
            $ref: "./common.yml#/components/schemas/OperationLog"

definitions:
  UpdateGroup:
    type: object
    description: "Update group."
    properties:
      addItems:
        type: array
        description: "Add items."
        items:
          type: string
          format: uuid
      removeItems:
        type: array
        description: "Remove items."
        items:
          type: string
          format: uuid