MyINPulse/documentation/openapi/src/main.yaml

openapi: 3.0.3
info:
  title: MyInpulse Backend API
  description: This serves as an OpenAPI documentation for the MyInpulse backend service, covering operations for Entrepreneurs, Admins, and shared functionalities.
  version: 0.2.1

tags:
  - name: Entrepreneurs API
    description: API endpoints primarily for Entrepreneur users.
  - name: Admin API
    description: API endpoints restricted to Admin users for management tasks.
  - name: Shared API
    description: API endpoints accessible by both Entrepreneurs and Admins.
  - name: Account Management API
    description: API endpoints related to user account management.

components:
  schemas:
    user:
      $ref: "models.yaml#/user"
    user-entrepreneur:
      $ref: "models.yaml#/user-entrepreneur"
    user-admin:
      $ref: "models.yaml#/user-admin"
    sectionCell:
      $ref: "models.yaml#/sectionCell"
    project:
      $ref: "models.yaml#/project"
    report:
      $ref: "models.yaml#/report"
    appointment:
      $ref: "models.yaml#/appointment"
    joinRequest:
      $ref: "models.yaml#/joinRequest"
    ApiError:
      type: object
      properties:
        timestamp:
           type: string
           format: date-time
           description: Timestamp when the error occurred.
        status:
           type: integer
           description: HTTP status code.
        error:
           type: string
           description: High-level error description (e.g., Bad Request, Not Found).
        message:
           type: string
           description: A human-readable description of the error specific to this occurrence.
           example: Required field 'projectName' is missing.
        path:
           type: string
           description: The path of the request that triggered the error.
      required:
        - timestamp
        - status
        - error
        - message
        - path

  securitySchemes:
      MyINPulse:
        type: oauth2
        description: OAuth2 authentication using Keycloak.
        flows:
          implicit:
            authorizationUrl: '{keycloakBaseUrl}/realms/{keycloakRealm}/protocol/openid-connect/auth'
            scopes:
              MyINPulse-admin: Grants administrator access.
              MyINPulse-entrepreneur: Grants standard entrepreneur user access.

servers:
    - url: '{serverProtocol}://{serverHost}:{serverPort}'
      description: API Server Environment
      variables:
        serverProtocol:
          enum: [http, https]
          default: http
        serverHost:
          default: localhost
        serverPort:
          enum: ['8081'] 
          default: '8081'
        keycloakBaseUrl:
          default: http://localhost:7080
          description: Base URL for the Keycloak server.
        keycloakRealm:
          default: MyInpulseRealm 
          description: Keycloak realm name.

paths:
  #       _   _                   _   _        _          _ 
  #      | | | |_ __   __ _ _   _| |_| |__    / \   _ __ (_)
  #      | | | | '_ \ / _` | | | | __| '_ \  / _ \ | '_ \| |
  #      | |_| | | | | (_| | |_| | |_| | | |/ ___ \| |_) | |
  #       \___/|_| |_|\__,_|\__,_|\__|_| |_/_/   \_\ .__/|_|
  #                                                |_|      

  /accounts/finalize:
    $ref: "./unauthApi.yaml#/paths/~1accounts~1finalize"

  #          _    ____  __  __ ___ _   _      _    ____ ___
  #         / \  |  _ \|  \/  |_ _| \ | |    / \  |  _ \_ _|
  #        / _ \ | | | | |\/| || ||  \| |   / _ \ | |_) | |
  #       / ___ \| |_| | |  | || || |\  |  / ___ \|  __/| |
  #      /_/   \_\____/|_|  |_|___|_| \_| /_/   \_\_|  |___|
  #
  /admin/pending-accounts:
    $ref: "./adminApi.yaml#/paths/~1admin~1pending-accounts"
  /admin/accounts/validate/{userId}:
    $ref: "./adminApi.yaml#/paths/~1admin~1accounts~1validate~1{userId}"
  /admin/projects:
    $ref: "./adminApi.yaml#/paths/~1admin~1projects"
  /admin/projects/pending:
    $ref: "./adminApi.yaml#/paths/~1admin~1projects~1pending"
  /admin/projects/pending/decision/{pendingProjectId}:
    $ref: "./adminApi.yaml#/paths/~1admin~1projects~1pending~1decision~1{pendingProjectId}"
  /admin/appointments/report/{appointmentId}:
    $ref: "./adminApi.yaml#/paths/~1admin~1appointments~1report~1{appointmentId}"
  /admin/projects/{projectId}:
    $ref: "./adminApi.yaml#/paths/~1admin~1projects~1{projectId}" 
  /admin/make-admin/{userId}: # Renamed for clarity
    $ref: "./adminApi.yaml#/paths/~1admin~1make-admin~1{userId}"

  #       ____  _                        _      _    ____ ___
  #      / ___|| |__   __ _ _ __ ___  __| |    / \  |  _ \_ _|
  #      \___ \| '_ \ / _` | '__/ _ \/ _` |   / _ \ | |_) | |
  #       ___) | | | | (_| | | |  __/ (_| |  / ___ \|  __/| |
  #      |____/|_| |_|\__,_|_|  \___|\__,_| /_/   \_\_|  |___|
  #
  /shared/appointments/upcoming:
    $ref: "./sharedApi.yaml#/paths/~1shared~1appointments~1upcoming"
  /shared/projects/sectionCells/{projectId}/{sectionId}/{date}:
    $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1sectionCells~1{projectId}~1{sectionId}~1{date}"
  /shared/projects/entrepreneurs/{projectId}:
    $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1entrepreneurs~1{projectId}"
  /shared/projects/admins/{projectId}:
    $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1admins~1{projectId}"
  /shared/projects/appointments/{projectId}:
    $ref: "./sharedApi.yaml#/paths/~1shared~1projects~1appointments~1{projectId}"
  /shared/appointments/report/{appointmentId}:
    $ref: "./sharedApi.yaml#/paths/~1shared~1appointments~1report~1{appointmentId}"
  /shared/appointments/request:
    $ref: "./sharedApi.yaml#/paths/~1shared~1appointments~1request"

  #      _____ _   _ _____ ____  _____ ____  ____  _____ _   _ _____ _   _ ____
  #     | ____| \ | |_   _|  _ \| ____|  _ \|  _ \| ____| \ | | ____| | | |  _ \
  #     |  _| |  \| | | | | |_) |  _| | |_) | |_) |  _| |  \| |  _| | | | | |_) |
  #     | |___| |\  | | | |  _ <| |___|  __/|  _ <| |___| |\  | |___| |_| |  _ <
  #     |_____|_|_\_| |_| |_| \_\_____|_|   |_| \_\_____|_| \_|_____|\___/|_| \_\
  #        / \  |  _ \_ _|
  #       / _ \ | |_) | |
  #      / ___ \|  __/| |
  #     /_/   \_\_|  |___|
  #
  /entrepreneur/projects/request-join/{projectId}:
     $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1projects~1request-join~1{projectId}"
  /entrepreneur/projects/request:
    $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1projects~1request"
  /entrepreneur/sectionCells:
    $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1sectionCells"
  /entrepreneur/sectionCells/{sectionCellId}:
    $ref: "./entrepreneurApi.yaml#/paths/~1entrepreneur~1sectionCells~1{sectionCellId}"