bonus-openapi3.spec.yaml

openapi: 3.0.3
info:
  title: B-VSA Semestrálny Projekt 2 - BONUS
  description: |
    Špecifikácia REST webových služieb slúžia pre detailný opis bonusovej funkcionality pre Semestrálny Projekt 2 
    v rámci predmetu B-VSA akademický rok 2022/2023. 
    
    Bonus je ohodnotený 3 bodmi.
    
    Pre dopyty na služby 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ť.

    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/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.
      parameters:
        - name: page
          description: Číslo stránky. Stránky sú indexované od 0.
          in: query
          schema:
            type: integer
            default: 0
          required: false
          allowEmptyValue: false
        - name: size
          description: Maximálny počet jednej stránky (t.j. veľkosť stránky).
          in: query
          schema:
            type: integer
            default: 20
          required: false
          allowEmptyValue: false
      requestBody:
        description: |
          Telo dopytu s kritériami vyhľadávania. Kritéria môžu by v ľubovoľnom poradí a v ľubovoľnom zastúpení.
          Medzi viacerými kritériami je operátor AND.
        content:
          application/json:
            schema:
              anyOf:
                - type: object
                  properties:
                    studentId:
                      description: Vyhľadanie podľa identifikátora študenta. Nesmie byť v kombinácii s atribútom teacherId.
                      type: integer
                      format: int64
                    teacherId:
                      description: Vyhľadanie podľa identifikátora učiteľa. Nesmie byť v kombinácii s atribútom studentId.
                      type: integer
                      format: int64
                    department:
                      type: string
                    publishedOn:
                      type: string
                      format: date
                    type:
                      type: string
                      enum:
                        - BACHELOR
                        - MASTER
                        - DISSERTATION
                    status:
                      type: string
                      enum:
                        - FREE_TO_TAKE
                        - IN_PROGRESS
                        - SUBMITTED
      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: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Thesis'
                  page:
                    type: object
                    properties:
                      number:
                        type: integer
                      size:
                        type: integer
                      totalElements:
                        type: integer
                      totalPages:
                        type: integer
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        500:
          $ref: '#/components/responses/ServerError'
  /api/search/teachers:
    post:
      operationId: searchTeachers
      tags:
        - teacher
      summary: Search teachers
      description: Vyhľadanie učiteľov na základe kritérií tela dopytu.
      parameters:
        - name: page
          description: Číslo stránky. Stránky sú indexované od 0.
          in: query
          schema:
            type: integer
            default: 0
          required: false
          allowEmptyValue: false
        - name: size
          description: Maximálny počet jednej stránky (t.j. veľkosť stránky).
          in: query
          schema:
            type: integer
            default: 20
          required: false
          allowEmptyValue: false
      requestBody:
        description: |
          Telo dopytu s kritériami vyhľadávania. Kritéria môžu by v ľubovoľnom poradí a v ľubovoľnom zastúpení.
          Medzi viacerými kritériami je operátor AND.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                institute:
                  type: string
      responses:
        200:
          description: Zoznam učiteľov vyhovujúcich kritériu. Ak nie sú nájdený žiadny učitelia je vrátený prázdny zoznam.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Teacher'
                  page:
                    type: object
                    properties:
                      number:
                        type: integer
                      size:
                        type: integer
                      totalElements:
                        type: integer
                      totalPages:
                        type: integer
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        500:
          $ref: '#/components/responses/ServerError'
  /api/search/students:
    post:
      operationId: searchStudents
      tags:
        - bonus
      summary: Search students
      description: Vyhľadanie študentov na základe kritérií tela dopytu.
      parameters:
        - name: page
          description: Číslo stránky. Stránky sú indexované od 0.
          in: query
          schema:
            type: integer
            default: 0
          required: false
          allowEmptyValue: false
        - name: size
          description: Maximálny počet jednej stránky (t.j. veľkosť stránky).
          in: query
          schema:
            type: integer
            default: 20
          required: false
          allowEmptyValue: false
      requestBody:
        description: |
          Telo dopytu s kritériami vyhľadávania. Kritéria môžu by v ľubovoľnom poradí a v ľubovoľnom zastúpení.
          Medzi viacerými kritériami je operátor AND.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                year:
                  type: integer
      responses:
        200:
          description: Zoznam študentov vyhovujúcich kritériu. Ak nie sú nájdený žiadny študenti je vrátený prázdny zoznam.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Student'
                  page:
                    type: object
                    properties:
                      number:
                        type: integer
                      size:
                        type: integer
                      totalElements:
                        type: integer
                      totalPages:
                        type: integer
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        500:
          $ref: '#/components/responses/ServerError'
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'
    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'
    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
        password:
          type: string
          format: password
        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
    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
security:
  - basicAuth: [ ]