ProjectManagmentTool/api/employee.yml

openapi: 3.0.1
info:
  title: Employees Management Micro-Service
  description: "\n## Overview\n\nEmployees Management Service API manages the employees\
    \ of HighTec Gmbh including their qualifications. It offers the possibility to\
    \ create, read, update and delete employees and qualifications. Existing employees\
    \ can be assigned new qualifications or have them withdrawn. \nThe API is organized\
    \ around REST. It has predictable resource-oriented URLs, accepts JSON-encoded\
    \ request bodies, returns JSON-encoded responses, uses standard HTTP response\
    \ codes and authentication.\n\n## Authentication\n\nEmployees Management Service\
    \ API uses JWTs to authenticate requests. You will receive a bearer token by making\
    \ a POST-Request in IntelliJ on:\n\n\n```\nPOST http://keycloak.szut.dev/auth/realms/szut/protocol/openid-connect/token\n\
    Content-Type: application/x-www-form-urlencoded\ngrant_type=password&client_id=employee-management-service&username=user&password=test\n\
    ```\n\n\nor by CURL\n```\ncurl -X POST 'http://keycloak.szut.dev/auth/realms/szut/protocol/openid-connect/token'\n\
    --header 'Content-Type: application/x-www-form-urlencoded'\n--data-urlencode 'grant_type=password'\n\
    --data-urlencode 'client_id=employee-management-service'\n--data-urlencode 'username=user'\n\
    --data-urlencode 'password=test'\n```\n\nTo get a bearer-token in Postman, you\
    \ have to follow the instructions in \n [Postman-Documentation](https://documenter.getpostman.com/view/7294517/SzmfZHnd).\n\
    \nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail.\
    \ API requests without authentication will also fail. Each request has the URL\
    \ \n `https://employee.szut.dev` and the address of the desired resource."
  version: 1.0.1
servers:
- url: ""
security:
- bearerAuth: []
paths:
  /qualifications/{id}:
    put:
      tags:
      - qualification-controller
      summary: updates a qualification
      operationId: updateQualification
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QualificationPostDTO'
        required: true
      responses:
        "401":
          description: not authorized
        "400":
          description: invalid JSON posted
        "200":
          description: updated qualification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualificationPostDTO'
        "404":
          description: resource not found
    delete:
      tags:
      - qualification-controller
      summary: deletes a qualification by id
      operationId: deleteQualificationByDesignation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        "401":
          description: not authorized
        "403":
          description: qualification is in use
        "204":
          description: delete successful
        "404":
          description: resource not found
  /employees/{id}:
    get:
      tags:
      - employee-controller
      summary: find employee by id
      operationId: findById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        "401":
          description: not authorized
        "200":
          description: employee
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResponseDTO'
        "404":
          description: resource not found
    put:
      tags:
      - employee-controller
      summary: updates employee by id - only changes the fields that are posted
      operationId: updateEmployee
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeRequestPutDTO'
        required: true
      responses:
        "401":
          description: not authorized
        "200":
          description: employee
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResponseDTO'
        "404":
          description: resource not found
    delete:
      tags:
      - employee-controller
      summary: deletes a employee by id
      operationId: deleteCustomer
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        "401":
          description: not authorized
        "204":
          description: delete successful
        "404":
          description: resource not found
  /qualifications:
    get:
      tags:
      - qualification-controller
      summary: delivers a list of all available qualifications
      operationId: findAll
      responses:
        "401":
          description: not authorized
        "200":
          description: list of qualifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualificationPostDTO'
    post:
      tags:
      - qualification-controller
      summary: creates a new qualification with its id and designation
      operationId: createQualification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QualificationPostDTO'
        required: true
      responses:
        "401":
          description: not authorized
        "201":
          description: created qualification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualificationPostDTO'
        "400":
          description: invalid JSON posted
  /employees:
    get:
      tags:
      - employee-controller
      summary: delivers a list of all employees
      operationId: findAll_1
      responses:
        "401":
          description: not authorized
        "200":
          description: list of employees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResponseDTO'
    post:
      tags:
      - employee-controller
      summary: creates a new employee
      operationId: createEmployee
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeRequestDTO'
        required: true
      responses:
        "401":
          description: not authorized
        "400":
          description: invalid JSON posted
        "201":
          description: created employee
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResponseDTO'
  /employees/{id}/qualifications:
    get:
      tags:
      - employee-controller
      summary: finds all qualifications of an employee by id
      operationId: findAllQualificationOfAEmployeeById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        "401":
          description: not authorized
        "200":
          description: employee with a list of his qualifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeNameAndSkillDataDTO'
        "404":
          description: resource not found
    post:
      tags:
      - employee-controller
      summary: adds a qualification to an employee by id
      operationId: addQualificationToEmployeeById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QualificationPostDTO'
        required: true
      responses:
        "401":
          description: not authorized
        "400":
          description: invalid JSON posted or employee already has this qualification
        "200":
          description: employee with a list of his qualifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeNameAndSkillDataDTO'
        "404":
          description: resource not found
    delete:
      tags:
      - employee-controller
      summary: deletes a qualification of an employee by id
      operationId: removeQualificationFromEmployee
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QualificationPostDTO'
        required: true
      responses:
        "401":
          description: not authorized
        "200":
          description: employee with a list of his qualifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeNameAndSkillDataDTO'
        "404":
          description: resource not found
  /qualifications/{id}/employees:
    get:
      tags:
      - qualification-controller
      summary: find employees by qualification id
      operationId: findAllEmployeesByQualification
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        "200":
          description: List of employees who have the desired qualification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeesForAQualificationDTO'
        "401":
          description: not authorized
        "404":
          description: qualification id does not exist
components:
  schemas:
    QualificationPostDTO:
      required:
      - skill
      type: object
      properties:
        skill:
          type: string
    EmployeeRequestPutDTO:
      type: object
      properties:
        lastName:
          type: string
        firstName:
          type: string
        street:
          type: string
        postcode:
          type: string
        city:
          type: string
        phone:
          type: string
        skillSet:
          type: array
          items:
            type: integer
            format: int64
    EmployeeResponseDTO:
      required:
      - city
      - firstName
      - lastName
      - phone
      - postcode
      - street
      type: object
      properties:
        id:
          type: integer
          format: int64
        lastName:
          type: string
        firstName:
          type: string
        street:
          type: string
        postcode:
          maxLength: 5
          minLength: 5
          type: string
        city:
          type: string
        phone:
          type: string
        skillSet:
          type: array
          items:
            $ref: '#/components/schemas/QualificationGetDTO'
    QualificationGetDTO:
      type: object
      properties:
        skill:
          type: string
        id:
          type: integer
          format: int64
    EmployeeRequestDTO:
      required:
      - city
      - firstName
      - lastName
      - phone
      - postcode
      - street
      type: object
      properties:
        lastName:
          type: string
        firstName:
          type: string
        street:
          type: string
        postcode:
          maxLength: 5
          minLength: 5
          type: string
        city:
          type: string
        phone:
          type: string
        skillSet:
          type: array
          items:
            type: integer
            format: int64
    EmployeeNameAndSkillDataDTO:
      type: object
      properties:
        id:
          type: integer
          format: int64
        lastName:
          type: string
        firstName:
          type: string
        skillSet:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/QualificationPostDTO'
    EmployeeNameDataDTO:
      type: object
      properties:
        id:
          type: integer
          format: int64
        lastName:
          type: string
        firstName:
          type: string
    EmployeesForAQualificationDTO:
      type: object
      properties:
        qualification:
          $ref: '#/components/schemas/QualificationGetDTO'
        employees:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/EmployeeNameDataDTO'
  securitySchemes:
    bearerAuth:
      type: http
      name: bearerAuth
      scheme: bearer
      bearerFormat: JWT