openapi.yaml

openapi: 3.0.1
info:
  description: This is the backend of the Lagunalink App.  You can find out more about this project at [https://github.com/jvegaf/LagunaLink-be](https://github.com/jvegaf/LagunaLink-be)
  version: 2.2.3
  title: LagunaLink Backend
  contact:
    email: josevega234@gmail.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
paths:
  /status:
    get:
      tags:
        - Status
      summary: Backend status
      responses:
        '200':
          $ref: '#/components/schemas/ApiResponse'


  /auth/signin:
    post:
      tags:
        - Auth
      summary: Authenticate in the Application
      requestBody:
        $ref: '#/components/requestBodies/SignInBody'
      responses:
        '200':
          $ref: '#/components/responses/AuthSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '450':
          $ref: '#/components/responses/Inactive'

  /auth/signup:
    post:
      tags:
        - Auth
      summary: Create new user account in the Application
      requestBody:
        $ref: '#/components/requestBodies/SignUpBody'
      responses:
        '201':
          description: Created

  /user/profile:
    get:
      tags:
        - User
      summary: get my profile
      security:
        - BearerAuth: [ ]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile:
                    $ref: '#/components/schemas/StudentProfile'


  /avatar/{userId}:
    get:
      summary: get avatar id from determinate user
      tags:
        - Avatar
      security:
        - BearerAuth: [ ]
      parameters:
        - name: userId
          in: path
          description: userId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  avatarId:
                    type: string
                    format: uuid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      summary: Upload avatar image of user account
      tags:
        - Avatar
      security:
        - BearerAuth: [ ]
      parameters:
        - name: userId
          in: path
          description: User ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          image/png:
            schema:
              type: string
              format: binary
          image/jpeg:
            schema:
              type: string
              format: binary

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  avatar:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Avatar
      security:
        - BearerAuth: [ ]
      summary: Remove avatar of determinate user
      parameters:
        - name: userId
          in: path
          description: User Id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /students/{studentId}:
    get:
      tags:
        - Student
      summary: Gets a Student By Id
      security:
        - BearerAuth: [ ]
      parameters:
        - name: studentId
          in: path
          description: Student ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  student:
                    $ref: '#/components/schemas/Student'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - Student
      summary: Update a Student
      security:
        - BearerAuth: [ ]
      parameters:
        - name: studentId
          in: path
          description: Student ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        $ref: '#/components/requestBodies/StudentPutBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  student:
                    $ref: '#/components/schemas/Student'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /enrollments/fetch/{studentId}:
    get:
      tags:
        - Enrollment
      security:
        - BearerAuth: [ ]
      summary: Returns a enrollments list of determinate student
      parameters:
        - name: studentId
          in: path
          description: Student ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  enrollments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Enrollment'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /companies:
    get:
      tags:
        - Company
      security:
        - BearerAuth: [ ]
      summary: Returns a list of registered companies.
      responses:
        '200':
          description: A JSON array of company objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /companies/{companyId}:
    get:
      tags:
        - Company
      security:
        - BearerAuth: [ ]
      summary: Gets a Company By Id
      parameters:
        - name: companyId
          in: path
          description: Company ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  company:
                    $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - Company
      security:
        - BearerAuth: [ ]
      summary: Update a Company
      parameters:
        - name: companyId
          in: path
          description: Company ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        $ref: '#/components/requestBodies/CompanyBody'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /job_openings:
    get:
      tags:
        - Job Opening
      security:
        - BearerAuth: [ ]
      summary: Returns a list of job openings.
      responses:
        '200':
          description: A JSON array of job opening objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobOpening'

    post:
      tags:
        - Job Opening
      security:
        - BearerAuth: [ ]
      summary: Create a new job opening
      requestBody:
        $ref: '#/components/requestBodies/JobOpeningBody'

      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_opening:
                    $ref: '#/components/schemas/JobOpening'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /job_openings/{jobOpeningId}:
    get:
      tags:
        - Job Opening
      security:
        - BearerAuth: [ ]
      summary: Gets a JobOpening By Id
      parameters:
        - name: jobOpeningId
          in: path
          description: JobOpening ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_opening:
                    $ref: '#/components/schemas/JobOpening'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - Job Opening
      security:
        - BearerAuth: [ ]
      summary: Update a JobOpening
      parameters:
        - name: jobOpeningId
          in: path
          description: JobOpening ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        $ref: '#/components/requestBodies/JobOpeningBody'
      responses:
        '200':
          description: A array of job opening objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobOpening'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    delete:
      tags:
        - Job Opening
      security:
        - BearerAuth: [ ]
      summary: turn Job Opening inactive
      parameters:
        - name: jobOpeningId
          in: path
          description: JobOpening ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'


  /enrollments/{enrollmentId}:
    get:
      tags:
        - Enrollment
      security:
        - BearerAuth: [ ]
      summary: Gets a Enrollment By Id
      parameters:
        - name: enrollmentId
          in: path
          description: Enrollment ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  enrollment:
                    $ref: '#/components/schemas/Enrollment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Enrollment
      security:
        - BearerAuth: [ ]
      summary: Remove determinate Enrollment
      parameters:
        - name: enrollmentId
          in: path
          description: Enrollment ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  enrollments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Enrollment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /enrollments/{jobOpeningId}:
    post:
      tags:
        - Enrollment
      security:
        - BearerAuth: [ ]
      summary: Create a new Enrollment of determinate Job Opening
      parameters:
        - name: jobOpeningId
          in: path
          description: JobOpening ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        $ref: '#/components/requestBodies/EnrollmentBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  enrollments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Enrollment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

components:
  schemas:
    Signin:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
      required:
        - email
        - password
    SignUp:
      type: object
      properties:
        email:
          type: string
          example: pepe@api.com
        password:
          type: string
        role:
          type: string
          enum:
            - ROLE_STUDENT
            - ROLE_COMPANY
      required:
        - email
        - password
        - role

    AuthResponse:
      type: object
      properties:
        userId:
          type: string
          format: uuid
        email:
          type: string
        accessToken:
          type: string
        avatar:
          type: string

      required:
        - userId
        - email
        - accessToken
        - role

    StudentProfile:
      type: object
      allOf:
        - $ref: '#/components/schemas/Student'
      properties:
        enrolls:
          type: array
          items:
            $ref: '#/components/schemas/Enrollment'
        jobOpenings:
          description: Set of Job Openings that are enrolled
          type: array
          items:
            $ref: '#/components/schemas/JobOpening'


    Student:
      type: object
      allOf:
        - $ref: '#/components/schemas/StudentRequest'
        - $ref: '#/components/schemas/StudentExtend'
      properties:
        id:
          type: string
          format: uuid
      required:
        - id
        - name
        - surname
        - lastname

    StudentRequest:
      type: object
      properties:
        name:
          type: string
          example: Ruben
        surname:
          type: string
          example: Navarro
        lastname:
          type: string
          example: Sanchez
      required:
        - name
        - surname
        - lastname

    StudentExtend:
      type: object
      properties:
        qualification:
          type: object
        languages:
          type: array
          items:
            $ref: "#/components/schemas/Language"
        job_experiences:
          type: array
          items:
            $ref: "#/components/schemas/JobExperience"

    CompanyRequest:
      type: object
      properties:
        name:
          type: string
          example: Charcuteria Pepi
        description:
          type: string
          example: "La charcutería es aquella carnicería especializada en la comercialización de los productos de la carne de cerdo y sus subproductos: fiambres y embutidos.​ Se suelen vender en estos establecimientos: salchichas, salchichones, chorizos, salami, jamón en diferentes formatos, aspic, etcétera"
        address:
          type: string
          example: Calle sal si puedes 40
        postalCode:
          type: integer
          example: 08080
        region:
          type: string
          example: Madrid
        city:
          type: string
          example: Mostoles
      required:
        - name
        - description
        - address
        - postalCode
        - region
        - city

    Company:
      type: object
      allOf:
        - $ref: '#/components/schemas/CompanyRequest'
      properties:
        id:
          type: string
          format: uuid
        job_openings:
          type: array
          items:
            $ref: '#/components/schemas/JobOpening'

    CompanyProfile:
      type: object
      allOf:
        - $ref: '#/components/schemas/Company'
      properties:
        jobOpenings:
          type: array
          items:
            $ref: '#/components/schemas/JobOpening'
        enrolls:
          type: array
          items:
            $ref: '#/components/schemas/Enrollment'
        students:
          type: array
          items:
            $ref: '#/components/schemas/Student'

    Language:
      type: object
      properties:
        name:
          type: string
          example: Italiano
        speak:
          type: integer
          minimum: 1
          maximum: 5
        write:
          type: integer
          minimum: 1
          maximum: 5
      required:
        - name
        - speak
        - write

    Qualification:
      type: object
      properties:
        title:
          type: string
          example: Grado Superior en Desarrollo de Aplicaciones Multiplaforma
        start_date:
          type: string
          format: date
          example: 2016-09
        end_date:
          type: string
          format: date
          example: 2018-06
      required:
        - title
        - start_date
        - end_date

    JobExperience:
      type: object
      properties:
        company:
          type: string
          example: Talleres Jumosa
        position:
          type: string
          example: Aprendiz de Mecanico
        responsibilities:
          type: string
          example: Cambiar Aceite
        start_date:
          type: string
          format: date
          example: 2018-06
        end_date:
          type: string
          format: date
          example: 2020-06
      required:
        - company
        - position
        - responsibilities
        - start_date
        - end_date

    JobOpeningRequest:
      type: object
      properties:
        company:
          type: string
          format: uuid
        position:
          type: string
          example: Pastelero
        description:
          type: string
          example: Obrador situado en Zaragoza, necesita incorporar un puesto de trabajo en la categoría de oficial de primera de manera estable
        responsibilities:
          type: string
          example: Tareas en el obrador
        conditions:
          type: string
          example: '- Estabilidad laboral
                    - Buena remuneración
                    - Buenas condiciones
                    - Formación
                    - Buen equipo y buen ambiente laboral'
        qualification:
          type: string
          example: Grado Superior de Cocina
        prevExperience:
          type: string
          example: de 3 a 5 años
        hiringDate:
          type: string
          example: 05-04-2021
      required:
        - company
        - position
        - responsibilities
        - hiringDate
    JobOpening:
      allOf:
        - $ref: '#/components/schemas/JobOpeningRequest'
        - type: object
          properties:
            id:
              type: string
              format: uuid
            createdAt:
              type: string

    User:
      type: object
      properties:
        email:
          type: string
          example: juan@api.com
        role:
          type: string
          enum:
            - ROLE_STUDENT
            - ROLE_COMPANY
        password:
          type: string
      required:
        - id
        - email
        - role
        - password

    EnrollmentBasic:
      type: object
      properties:
        student:
          type: string
          format: uuid
        jobOpening:
          type: string
          format: uuid
        enrollmentDate:
          type: string
          format: date
          example: 2018-06
      required:
        - student
        - jobOpening
        - enrollmentDate

    Enrollment:
      type: object
      allOf:
        - $ref: '#/components/schemas/EnrollmentBasic'
      properties:
        id:
          type: string
          format: uuid

    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 200
        type:
          type: string
        message:
          type: string
          example: OK

    NoContentResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        type:
          type: string
        message:
          type: string

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    AuthSuccess:
      description: Authentication Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthResponse'

    Success:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
    NoContent:
      description: No Content
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NoContentResponse'
    Unauthorized:
      description: Access token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Access token does not have the required scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Inactive:
      description: The account is not verified yet
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  requestBodies:
    SignUpBody:
      description: A JSON object containing email password and selected role
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignUp'
    SignInBody:
      description: A JSON object containing email and password
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Signin'
    UserBody:
      description: A JSON object containing user information
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
    StudentPutBody:
      description: A JSON object containing student information
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StudentExtend'
    CompanyBody:
      description: A JSON object containing company information
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CompanyRequest'
    JobOpeningBody:
      description: A JSON object containing job opening information
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobOpeningRequest'
    EnrollmentBody:
      description: A JSON object containing enrollment information
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnrollmentBasic'