openapi3.spec.yaml

openapi: 3.0.3
info:
  title: B-VSA Semestrálny Projekt 2
  description: |
    Špecifikácia REST webových služieb slúžia pre detailný opis požadovanej funkcionality pre Semestrálny Projekt 2 
    v rámci predmetu B-VSA akademický rok 2022/2023.
    
    Pre dopyty na väčšinu služieb (okrem createStudent a createTeacher) je potrebné byť prihlásený. Služby pracujú s Basic
    autentifikáciou. Každý študent a učiteľ je používateľ systému, ktorý sa môže prihlásiť.
    Niektoré služby vyžadujú autorizáciu/oprávnenie pre ich dopyt. Služba, ktorá je obmedzená oprávneniami, to má uvedené
    v popise služby.
    
    Ak služba má vrátiť jeden objekt a nie je nájdený namiesto hodnoty null vráti odpoveď 404. V prípade nečakanej chyby
    má byť odpoveď s kódom 500 a v správe dôvod vzniku chyby (správa zo vzniknutej Exception).
  version: 1.0.0
  license:
    name: Unlicense license
    url: https://unlicense.org
externalDocs:
  url: https://github.com/Interes-Group/b-vsa-ls23-project2-solution/blob/master/README.md
  description: Znenie celého zadania
servers:
  - url: 'http://localhost:8080'
tags:
  - name: student
  - name: teacher
  - name: thesis
paths:
  /api/students:
    post:
      operationId: createStudent
      tags:
        - student
      summary: Create new student
      description: |
        Vytvorenie nového študenta. Po vytvorení je možné sa prihlásiť ako novo registrovaný študent.
        Služba je verejne dostupná bez prihlásenia.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStudentRequest'
      responses:
        201:
          description: Objekt novo vytvoreného študenta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Student'
        500:
          $ref: '#/components/responses/ServerError'
    get:
      operationId: getAllStudents
      tags:
        - student
      summary: Get all students
      description: Získanie zoznamu všetkých študentov.
      responses:
        200:
          description: Zoznam všetkých študentov v systéme. Ak v systéme neexistujú žiadny študenti je vrátení prázdny zoznam.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Student'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
  /api/students/{id}:
    get:
      operationId: getStudent
      tags:
        - student
      summary: Get a student by id
      description: Získanie študenta podľa identifikátora.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Objekt študenta so zadaným identifikátorom. V prípade, že taký študent neexistuje tak je vrátená odpoveď 404.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Student'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
    delete:
      operationId: deleteStudent
      tags:
        - student
      summary: Delete a student by id
      description: |
        Vymazanie študenta podľa identifikátora. 
        Vymazať študenta môže iba učiteľ (t.j. prihlásený je učiteľ) alebo prihlásený študent s rovnakým identifikátorom ako v dopyte.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Objekt študenta ktorý bol vymazaný.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Student'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
  /api/teachers:
    post:
      operationId: createTeacher
      tags:
        - teacher
      summary: Create new teacher
      description: |
        Vytvorenie nového učiteľa. Po vytvorení je možné sa prihlásiť ako novo registrovaný učiteľ.
        Služba je verejne dostupná bez prihlásenia.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeacherRequest'
      responses:
        201:
          description: Objekt novo vytvoreného učiteľa.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Teacher'
        500:
          $ref: '#/components/responses/ServerError'
    get:
      operationId: getAllTeachers
      tags:
        - teacher
      summary: Get all teachers
      description: Získanie zoznamu všetkých učiteľov.
      responses:
        200:
          description: Zoznam všetkých učiteľov v systéme. Ak v systéme neexistujú žiadny učitelia je vrátený prázdny zoznam.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Teacher'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
  /api/teachers/{id}:
    get:
      operationId: getTeacher
      tags:
        - teacher
      summary: Get a teacher by id
      description: Získanie učiteľa podľa identifikátora.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Objekt učiteľa so zadaným identifikátorom. V prípade, že taký študent neexistuje tak je vrátená odpoveď 404.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Teacher'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
    delete:
      operationId: deleteTeacher
      tags:
        - teacher
      summary: Delete a teacher by id
      description: |
        Vymazanie učiteľa podľa identifikátora.
        Vymazať učiteľa môže iba prihlásený učiteľ, ktorého identifikátor sa zhoduje s poskytnutým identifikátorom v dopyte.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Objekt študenta ktorý bol vymazaný.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Teacher'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
  /api/theses:
    post:
      operationId: createThesis
      tags:
        - thesis
      summary: Create new thesis
      description: |
        Vytvorenie záverečnej práce. Vytvoriť záverečnú prácu môže iba učiteľ. 
        Vytvorená záverečná práca je vytvorená pod prihláseným učiteľom.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateThesisRequest'
      responses:
        201:
          description: Objekt novo vytvorenej záverečnej práce.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thesis'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
    get:
      operationId: getAllTheses
      tags:
        - thesis
      summary: Get all theses
      description: Získanie zoznamu záverečných prác.
      responses:
        200:
          description: Zoznam všetkých záverečných prác v systéme. Ak nie sú vypísané žiadne práce je vrátený prázdny zoznam.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Thesis'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
  /api/theses/{id}:
    get:
      operationId: getThesis
      tags:
        - thesis
      summary: Get a thesis by id
      description: Získanie záverečnej práce podľa identifikátora.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: |
            Objekt záverečnej práce so zadaným identifikátorom. 
            V prípade, že taká záverečná práca neexistuje, tak je vrátená odpoveď 404.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thesis'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
    delete:
      operationId: deleteThesis
      tags:
        - thesis
      summary: Delete a thesis by id
      description: |
        Vymazanie záverečnej práce podľa identifikátora.
        Vymazať prácu môže iba prihlásený učiteľ, ktorý prácu vypísal.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Objekt záverečnej práce, ktorý bola vymazaná.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thesis'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
  /api/theses/{id}/assign:
    post:
      operationId: assignThesis
      tags:
        - thesis
      summary: Assign a thesis by id to a student
      description: |
        Priradenie záverečnej práce podľa identifikátora študentovi.
        Ak je prihlásený študent v dopyte je práca priradená jemu.
        Ak je prihlásený učiteľ je práca priradená študentovi podľa identifikátora v objekte tele dopytu.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Objekt s identifikátorom študenta v prípade ak je prihlásený učiteľ. Ak je prihlásený študent telo je ignorované.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                studentId:
                  type: integer
                  format: int64
      responses:
        200:
          description: Objekt záverečnej práce, ktorá bola priradená študentovi. Vrátený objekt má obsahovať aj objekt študenta priradeného k prácu.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thesis'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
  /api/theses/{id}/submit:
    post:
      operationId: submitThesis
      tags:
        - thesis
      summary: Submit a thesis by id assigned to a student
      description: |
        Odovzdanie záverečnej práce podľa identifikátora.
        Ak je prihlásený študent v dopyte musí sa zhodovať so študentom priradeného k práci.
        Ak je prihlásený učiteľ je práca odovzdaná študentom podľa identifikátora v objekte tele dopytu,
        ktorý sa musí zhodovať so študentom priradeného k prác.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Objekt s identifikátorom študenta v prípade ak je prihlásený učiteľ. Ak je prihlásený študent telo je ignorované.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                studentId:
                  type: integer
                  format: int64
      responses:
        200:
          description: Objekt záverečnej práce, ktorá bola odovzdaná študentom.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thesis'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
  /api/search/theses:
    post:
      operationId: searchTheses
      tags:
        - thesis
      summary: Search theses by a teacher or a student
      description: Vyhľadanie záverečnej práce na základe kritérií tela dopytu.
      requestBody:
        description: |
          Telo dopytu je jeden z možných objektov. Buď sú práce vyhľadané podľa priradeného študenta, 
          alebo podľa učiteľa, ktorý vypísal záverečnú prácu.
        content:
          application/json:
            schema:
              anyOf:
                - type: object
                  properties:
                    studentId:
                      type: integer
                      format: int64
                - type: object
                  properties:
                    teacherId:
                      type: integer
                      format: int64
      responses:
        200:
          description: Zoznam záverečných prác vyhovujúcich kritériu. Ak nie sú vypísané žiadne práce je vrátený prázdny zoznam.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Thesis'
        401:
          $ref: '#/components/responses/Unauthorized'
        500:
          $ref: '#/components/responses/ServerError'
      security:
        - basicAuth: [ ]
components:
  schemas:
    Student:
      type: object
      description: Objekt študenta.
      required: [ id, aisId, email ]
      properties:
        id:
          description: Id študenta. V prípade ak je použité AIS ID ako identifikátor študenta tak je táto hodnota rovnaká ako v atribúte aisId.
          type: integer
          format: int64
        aisId:
          description: AIS ID študenta. Zadané pri vytvorení študenta. Musí byť unikátne v rámci všetkých študentov.
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
        year:
          type: integer
        term:
          type: integer
        programme:
          type: string
        thesis:
          $ref: '#/components/schemas/Thesis'
    CreateStudentRequest:
      type: object
      description: Objekt študenta pre vytvorenie nového študenta.
      required: [ aisId, email, name, password ]
      properties:
        aisId:
          description: AIS ID študenta. Musí byť unikátne v rámci všetkých študentov.
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
        password:
          description: Heslo pre prihlásenie študenta. Heslo musí byť zaslané enkódované v BASE64.
          type: string
          format: password
        year:
          type: integer
        term:
          type: integer
        programme:
          type: string
    StudentAltResponse:
      type: object
      description: Objekt študenta s id záverečnej práce namiesto objektu.
      required: [ id, aisId, email ]
      properties:
        id:
          description: Id študenta. V prípade ak je použité AIS ID ako identifikátor študenta tak je táto hodnota rovnaká ako v atribúte aisId.
          type: integer
          format: int64
        aisId:
          description: AIS ID študenta. Zadané pri vytvorení študenta. Musí byť unikátne v rámci všetkých študentov.
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
        year:
          type: integer
        term:
          type: integer
        programme:
          type: string
        thesis:
          description: ID záverečnej práce priradené študentovi. Ak študent nemá priradenú prácu, tento atribút je vynechaný.
          type: integer
          format: int64
    Teacher:
      type: object
      description: Objekt učiteľa.
      required: [ id, aisId, email ]
      properties:
        id:
          description: Id učiteľa. V prípade ak je použité AIS ID ako identifikátor učiteľa tak je táto hodnota rovnaká ako v atribúte aisId.
          type: integer
          format: int64
        aisId:
          description: AIS ID učiteľa. Zadané pri vytvorení učiteľa. Musí byť unikátne v rámci všetkých učiteľov.
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
        institute:
          type: string
        department:
          type: string
        theses:
          type: array
          items:
            $ref: '#/components/schemas/Thesis'
    CreateTeacherRequest:
      type: object
      description: Objekt učiteľa pre vytvorenie nového učiteľa.
      required: [ aisId, email, password, name ]
      properties:
        aisId:
          description: AIS ID učiteľa. Musí byť unikátne v rámci všetkých učiteľov.
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
        password:
          description: Heslo pre prihlásenie učiteľa. Heslo musí byť zaslané enkódované v BASE64.
          type: string
          format: password
        institute:
          type: string
        department:
          type: string
    TeacherAltResponse:
      type: object
      description: Objekt študenta s identifikátormi záverečnej práce namiesto kolekcie objektov.
      required: [ id, aisId, email ]
      properties:
        id:
          description: Id učiteľa. V prípade ak je použité AIS ID ako identifikátor učiteľa tak je táto hodnota rovnaká ako v atribúte aisId.
          type: integer
          format: int64
        aisId:
          description: AIS ID učiteľa. Zadané pri vytvorení učiteľa. Musí byť unikátne v rámci všetkých učiteľov.
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
        institute:
          type: string
        department:
          type: string
        theses:
          type: array
          description: ID záverečných prác vytvorené učiteľom. Ak učiteľ nevytvoril žiadne záverečné práce je tento atribút vynechaný.
          items:
            type: integer
            format: int64
    Thesis:
      type: object
      description: Objekt záverečnej práce.
      required: [ id, registrationNumber, title, department, supervisor, type ]
      properties:
        id:
          type: integer
          format: int64
        registrationNumber:
          type: string
          pattern: ^FEI-\w+$
        title:
          type: string
        description:
          type: string
        department:
          type: string
        supervisor:
          $ref: '#/components/schemas/TeacherAltResponse'
        author:
          $ref: '#/components/schemas/StudentAltResponse'
        publishedOn:
          type: string
          format: date
        deadline:
          type: string
          format: date
        type:
          type: string
          enum:
            - BACHELOR
            - MASTER
            - DISSERTATION
        status:
          type: string
          enum:
            - FREE_TO_TAKE
            - IN_PROGRESS
            - SUBMITTED
    CreateThesisRequest:
      type: object
      description: Objekt záverečnej práce pre vytvorenie novej záverečnej práce.
      required: [ registrationNumber, title, type ]
      properties:
        registrationNumber:
          type: string
          pattern: ^FEI-\w+$
        title:
          type: string
        description:
          type: string
        type:
          type: string
          enum:
            - BACHELOR
            - MASTER
            - DISSERTATION
    Message:
      type: object
      required: [ code, message ]
      description: Objekt správy pre vrátenie informácii o dopyte. Využité najmä v prípade vrátenia odpovedi pri chybe dopytu alebo spracovania.
      properties:
        code:
          type: integer
          pattern: ^\d{3}$
        message:
          type: string
        error:
          type: object
          properties:
            type:
              type: string
            trace:
              type: string
  responses:
    Unauthorized:
      description: |
        Unauthorized request. 
        Dopyt musí byt autorizovaný platnou autentifikačnou schémou. Kód v odpovedi je vždy 401.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Message'
      headers:
        WWW_Authenticate:
          schema:
            type: string
    Forbidden:
      description: |
        Authorized user doesn't have permission for the request.
        Autentifikovaný používateľ nemá oprávnenie na dopyt. Kód v odpovedi je vždy 403.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Message'
    NotFound:
      description: |
        Requested resource was not found.
        Objekt nebolo možné nájsť. Kód v odpovedi je vždy 404.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Message'
    ServerError:
      description: |
        Internal server error.
        Nepredvídateľná chyba na servery pri spracovaní dopytu. Kód v odpovedi je vždy 500.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Message'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic