openapi: "3.0.3"
info:
  title: legalconsenthub
  version: 0.1.0
  description: A platform for digital applications, approvals and discussions.
  contact:
    name: Denis Lugowski
    email: denis.lugowski@gmail.com

servers:
  - url: http://localhost:8080

security:
  - bearerAuth: []

paths:
  ####### Application Forms #######
  /application-forms:
    get:
      summary: Get all ApplicationForms
      operationId: getAllApplicationForms
      tags:
        - application-form
      parameters:
        - in: query
          name: organizationId
          schema:
            type: string
          description: Filter application forms by organization ID
      responses:
        "200":
          description: Paged list of application forms
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedApplicationFormDto"
        "500":
          description: Internal server error
    post:
      summary: Create a new ApplicationForm
      operationId: createApplicationForm
      tags:
        - application-form
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationFormDto"
      responses:
        "201":
          description: Successfully created application form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get a specific ApplicationForm
      operationId: getApplicationFormById
      tags:
        - application-form
      responses:
        "200":
          description: Get application form by ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    put:
      summary: Updates a ApplicationForm
      operationId: updateApplicationForm
      tags:
        - application-form
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationFormDto"
      responses:
        "200":
          description: Successfully updated application form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a ApplicationForm
      operationId: deleteApplicationForm
      tags:
        - application-form
      responses:
        "204":
          description: Application Form successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/pdf:
    get:
      summary: Returns the application form rendered as PDF
      operationId: getApplicationFormPdf
      tags:
        - application-form
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Application form as PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/html:
    get:
      summary: Returns the application form rendered as HTML
      operationId: getApplicationFormHtml
      tags:
        - application-form
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Application form as HTML
          content:
            text/html:
              schema:
                type: string
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/submit:
    post:
      summary: Submit an application form
      operationId: submitApplicationForm
      tags:
        - application-form
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Application form successfully submitted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{applicationFormId}/subsections/{subsectionId}/form-elements:
    post:
      summary: Add a new form element to a specific subsection
      operationId: addFormElementToSubSection
      tags:
        - application-form
      parameters:
        - name: applicationFormId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the application form
        - name: subsectionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the form element subsection
        - name: position
          in: query
          required: true
          schema:
            type: integer
          description: The position to insert the form element
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FormElementDto"
      responses:
        "201":
          description: Form element successfully added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/versions:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get all versions of an application form
      operationId: getApplicationFormVersions
      tags:
        - application-form-version
      responses:
        "200":
          description: List of versions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApplicationFormVersionListItemDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/versions/{versionNumber}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: versionNumber
        in: path
        required: true
        schema:
          type: integer
    get:
      summary: Get specific version with full snapshot
      operationId: getApplicationFormVersion
      tags:
        - application-form-version
      responses:
        "200":
          description: Version details with snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormVersionDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/versions/{versionNumber}/restore:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: versionNumber
        in: path
        required: true
        schema:
          type: integer
    post:
      summary: Restore a specific version
      operationId: restoreApplicationFormVersion
      tags:
        - application-form-version
      responses:
        "200":
          description: Restored application form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Application Form Templates #######
  /application-form-templates:
    get:
      summary: Get all ApplicationFormTemplates
      operationId: getAllApplicationFormTemplates
      tags:
        - application-form-template
      responses:
        "200":
          description: Paged list of application form templates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedApplicationFormDto"
        "500":
          description: Internal server error
    post:
      summary: Create a new ApplicationFormTemplate
      operationId: createApplicationFormTemplate
      tags:
        - application-form-template
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationFormDto"
      responses:
        "201":
          description: Successfully created application form template
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-form-templates/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get a specific ApplicationFormTemplate
      operationId: getApplicationFormTemplateById
      tags:
        - application-form-template
      responses:
        "200":
          description: Get application form template by ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    put:
      summary: Updates a ApplicationFormTemplate
      operationId: updateApplicationFormTemplate
      tags:
        - application-form-template
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationFormDto"
      responses:
        "200":
          description: Successfully updated application form template
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a ApplicationFormTemplate
      operationId: deleteApplicationFormTemplate
      tags:
        - application-form-template
      responses:
        "204":
          description: Application Form Template successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Users #######
  /users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Get a specific user
      operationId: getUserById
      tags:
        - user
      responses:
        "200":
          description: Get user by ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a user
      operationId: deleteUser
      tags:
        - user
      responses:
        "204":
          description: User successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /users/{id}/email-preferences:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    put:
      summary: Update user email preferences
      operationId: updateUserEmailPreferences
      tags:
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEmailPreferencesDto"
      responses:
        "200":
          description: Email preferences updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Comments #######
  /comments/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    put:
      summary: Update a comment
      operationId: updateComment
      tags:
        - comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommentDto"
      responses:
        "200":
          description: Successfully updated comment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a comment
      operationId: deleteComment
      tags:
        - comment
      responses:
        "204":
          description: Comment successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{applicationFormId}/comments:
    parameters:
      - name: applicationFormId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get comments for specific application form
      operationId: getCommentsByApplicationFormId
      tags:
        - comment
      responses:
        "200":
          description: Get comments for application form ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedCommentDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{applicationFormId}/form-elements/{formElementId}/comments:
    parameters:
      - name: applicationFormId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: formElementId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      summary: Create a new comment for a form element
      operationId: createComment
      tags:
        - comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCommentDto"
      responses:
        "201":
          description: Successfully created comment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Roles #######
  /roles:
    get:
      summary: Get all roles
      operationId: getAllRoles
      tags:
        - role
      responses:
        "200":
          description: List of roles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RoleDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    post:
      summary: Create a new role
      operationId: createRole
      tags:
        - role
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRoleDto"
      responses:
        "201":
          description: Successfully created role
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /roles/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get a specific role
      operationId: getRoleById
      tags:
        - role
      responses:
        "200":
          description: Get role by ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a role
      operationId: deleteRole
      tags:
        - role
      responses:
        "204":
          description: Role successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Notifications #######
  /notifications:
    get:
      summary: Get notifications for the current user
      operationId: getNotifications
      tags:
        - notification
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID to get notifications for
        - in: query
          name: page
          schema:
            type: integer
            default: 0
          description: Page number
        - in: query
          name: size
          schema:
            type: integer
            default: 20
          description: Page size
      responses:
        "200":
          description: Paged list of notifications
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedNotificationDto"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
    post:
      summary: Create a new notification
      operationId: createNotification
      tags:
        - notification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateNotificationDto"
      responses:
        "201":
          description: Successfully created notification
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/unread:
    get:
      summary: Get unread notifications for the current user
      operationId: getUnreadNotifications
      tags:
        - notification
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID to get unread notifications for
      responses:
        "200":
          description: List of unread notifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotificationDto"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "403":
          description: User is not authorized to access this organization
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/unread/count:
    get:
      summary: Get count of unread notifications for a user (public endpoint)
      operationId: getUnreadNotificationCount
      tags:
        - notification
      parameters:
        - in: query
          name: userId
          required: true
          schema:
            type: string
          description: Keycloak user ID to get notification count for
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID to get notification count for
      responses:
        "200":
          description: Count of unread notifications
          content:
            application/json:
              schema:
                type: integer
                format: int64
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/mark-all-read:
    put:
      summary: Mark all notifications as read for the current user
      operationId: markAllNotificationsAsRead
      tags:
        - notification
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID to mark notifications as read for
      responses:
        "204":
          description: All notifications marked as read
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "403":
          description: User is not authorized to access this organization
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/clear-all:
    delete:
      summary: Clear all notifications for the current user
      operationId: clearAllNotifications
      tags:
        - notification
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID to clear notifications for
      responses:
        "204":
          description: All notifications cleared
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "403":
          description: User is not authorized to access this organization
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/{id}/mark-read:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    put:
      summary: Mark a specific notification as read
      operationId: markNotificationAsRead
      tags:
        - notification
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID for authorization
      responses:
        "200":
          description: Notification marked as read
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationDto"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "403":
          description: User is not authorized to access this organization
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  ####### Files #######
  /files:
    get:
      summary: Get all files
      operationId: getAllFiles
      tags:
        - file
      responses:
        "200":
          description: Successful response
        "500":
          description: Internal server error
    post:
      summary: Upload a new file
      operationId: uploadFile
      tags:
        - file
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/UploadFileDto"
      responses:
        "201":
          description: File uploaded
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /files/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get a specific file
      operationId: getFileById
      tags:
        - file
      responses:
        "200":
          description: Get file by ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a file
      operationId: deleteFile
      tags:
        - file
      responses:
        "204":
          description: File successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ####### ApplicationFormDto #######
    ApplicationFormDto:
      type: object
      required:
        - name
        - formElementSections
        - isTemplate
      properties:
        id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        formElementSections:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSectionDto"
        isTemplate:
          type: boolean
          default: false
        organizationId:
          type: string
          nullable: true
        createdBy:
          $ref: "#/components/schemas/UserDto"
          nullable: true
        lastModifiedBy:
          $ref: "#/components/schemas/UserDto"
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        modifiedAt:
          type: string
          format: date-time
          nullable: true
        status:
          allOf:
            - $ref: "#/components/schemas/ApplicationFormStatus"
          nullable: true

    PagedApplicationFormDto:
      type: object
      allOf:
        - $ref: "#/components/schemas/Page"
      required:
        - content
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/ApplicationFormDto"

    ApplicationFormSnapshotDto:
      type: object
      required:
        - name
        - status
        - organizationId
        - sections
      properties:
        name:
          type: string
        status:
          $ref: "#/components/schemas/ApplicationFormStatus"
        organizationId:
          type: string
        sections:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSectionSnapshotDto"

    ####### ApplicationFormVersion #######
    ApplicationFormVersionDto:
      type: object
      required:
        - id
        - applicationFormId
        - versionNumber
        - name
        - status
        - organizationId
        - snapshot
        - createdBy
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        applicationFormId:
          type: string
          format: uuid
        versionNumber:
          type: integer
        name:
          type: string
        status:
          $ref: "#/components/schemas/ApplicationFormStatus"
        organizationId:
          type: string
        snapshot:
          $ref: "#/components/schemas/ApplicationFormSnapshotDto"
        createdBy:
          $ref: "#/components/schemas/UserDto"
        createdAt:
          type: string
          format: date-time

    ApplicationFormVersionListItemDto:
      type: object
      required:
        - id
        - applicationFormId
        - versionNumber
        - name
        - status
        - organizationId
        - createdBy
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        applicationFormId:
          type: string
          format: uuid
        versionNumber:
          type: integer
        name:
          type: string
        status:
          $ref: "#/components/schemas/ApplicationFormStatus"
        organizationId:
          type: string
        createdBy:
          $ref: "#/components/schemas/UserDto"
        createdAt:
          type: string
          format: date-time

    ####### Form #######
    FormElementSectionDto:
      type: object
      required:
        - title
        - formElementSubSections
      properties:
        id:
          type: string
          format: uuid
          nullable: true
        title:
          type: string
        shortTitle:
          type: string
        description:
          type: string
        formElementSubSections:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSubSectionDto"
        applicationFormId:
          type: string
          format: uuid
          nullable: true
        isTemplate:
          type: boolean
          default: false
          description: If true, this section is a template for spawning
        templateReference:
          type: string
          description: Unique reference key for this template section
        titleTemplate:
          type: string
          description: Title template with placeholder (e.g., "Modul{{triggerValue}}")
        spawnedFromElementReference:
          type: string
          description: Reference of the form element that triggered this section

    FormElementSectionSnapshotDto:
      type: object
      required:
        - title
        - subsections
      properties:
        title:
          type: string
        shortTitle:
          type: string
        description:
          type: string
        subsections:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSubSectionSnapshotDto"
        isTemplate:
          type: boolean
          default: false
        templateReference:
          type: string
        titleTemplate:
          type: string
        spawnedFromElementReference:
          type: string

    FormElementSubSectionDto:
      type: object
      required:
        - title
        - formElements
      properties:
        id:
          type: string
          format: uuid
          nullable: true
        title:
          type: string
        subtitle:
          type: string
        formElements:
          type: array
          items:
            $ref: "#/components/schemas/FormElementDto"
        formElementSectionId:
          type: string
          format: uuid
          nullable: true

    FormElementSubSectionSnapshotDto:
      type: object
      required:
        - title
        - elements
      properties:
        title:
          type: string
        subtitle:
          type: string
        elements:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSnapshotDto"

    FormElementDto:
      type: object
      required:
        - options
        - type
      properties:
        id:
          type: string
          format: uuid
          nullable: true
        reference:
          type: string
          description: Unique reference key for this form element (e.g., "art_der_massnahme")
        title:
          type: string
        description:
          type: string
        options:
          type: array
          items:
            $ref: "#/components/schemas/FormOptionDto"
        type:
          $ref: "#/components/schemas/FormElementType"
        formElementSubSectionId:
          type: string
          format: uuid
          nullable: true
        visibilityCondition:
          $ref: "#/components/schemas/FormElementVisibilityCondition"
        sectionSpawnTrigger:
          $ref: "#/components/schemas/SectionSpawnTriggerDto"
        isClonable:
          type: boolean
          default: false
          description: If true, user can add more instances of this element

    FormElementSnapshotDto:
      type: object
      required:
        - type
        - options
      properties:
        reference:
          type: string
        title:
          type: string
        description:
          type: string
        type:
          $ref: "#/components/schemas/FormElementType"
        options:
          type: array
          items:
            $ref: "#/components/schemas/FormOptionDto"
        visibilityCondition:
          $ref: "#/components/schemas/FormElementVisibilityCondition"
        sectionSpawnTrigger:
          $ref: "#/components/schemas/SectionSpawnTriggerDto"
        isClonable:
          type: boolean
          default: false

    FormOptionDto:
      type: object
      required:
        - value
        - label
        - processingPurpose
        - employeeDataCategory
      properties:
        value:
          type: string
        label:
          type: string
        processingPurpose:
          $ref: "#/components/schemas/ProcessingPurpose"
        employeeDataCategory:
          $ref: "#/components/schemas/EmployeeDataCategory"

    FormElementType:
      type: string
      enum:
        - SELECT
        - CHECKBOX
        - RADIOBUTTON
        - TEXTFIELD
        - TEXTAREA
        - SWITCH
        - TITLE_BODY_TEXTFIELDS
        - DATE

    FormElementVisibilityCondition:
      type: object
      required:
        - formElementConditionType
        - sourceFormElementReference
        - formElementExpectedValue
      properties:
        formElementConditionType:
          $ref: "#/components/schemas/VisibilityConditionType"
        sourceFormElementReference:
          type: string
          description: Reference key of the source form element to check
        formElementExpectedValue:
          type: string
          description: Expected value to compare against the source element's value property
        formElementOperator:
          $ref: "#/components/schemas/VisibilityConditionOperator"
          default: EQUALS

    VisibilityConditionType:
      type: string
      enum:
        - SHOW
        - HIDE

    VisibilityConditionOperator:
      type: string
      enum:
        - EQUALS
        - NOT_EQUALS
        - IS_EMPTY
        - IS_NOT_EMPTY

    SectionSpawnTriggerDto:
      type: object
      required:
        - templateReference
        - sectionSpawnConditionType
        - sectionSpawnOperator
      properties:
        templateReference:
          type: string
          description: Reference key of the section template to spawn
        sectionSpawnConditionType:
          $ref: "#/components/schemas/VisibilityConditionType"
        sectionSpawnExpectedValue:
          type: string
          description: Expected value to trigger spawning
        sectionSpawnOperator:
          $ref: "#/components/schemas/VisibilityConditionOperator"

    ####### UserDto #######
    UserDto:
      type: object
      required:
        - keycloakId
        - name
        - organizationId
      properties:
        keycloakId:
          type: string
        name:
          type: string
        organizationId:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        emailOnFormCreated:
          type: boolean
          default: true
        emailOnFormSubmitted:
          type: boolean
          default: true

    UpdateEmailPreferencesDto:
      type: object
      properties:
        email:
          type: string
          nullable: true
        emailOnFormCreated:
          type: boolean
        emailOnFormSubmitted:
          type: boolean

    UserStatus:
      type: string
      enum:
        - INVITED
        - ACTIVE
        - BLOCKED
        - SUSPENDED_SUBSCRIPTION

    UserRole:
      type: string
      description: "User's role in the organization"
      enum:
        - owner
        - admin
        - employer
        - works_council_member
        - employee

    ####### CommentDto #######
    CommentDto:
      type: object
      required:
        - id
        - message
        - applicationFormId
        - formElementId
        - createdAt
        - modifiedAt
        - createdBy
      properties:
        id:
          type: string
          format: uuid
        message:
          type: string
        applicationFormId:
          type: string
          format: uuid
        formElementId:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time
        createdBy:
          $ref: "#/components/schemas/UserDto"

    CreateCommentDto:
      type: object
      required:
        - message
      properties:
        message:
          type: string

    PagedCommentDto:
      type: object
      allOf:
        - $ref: "#/components/schemas/Page"
      required:
        - content
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/CommentDto"

    ####### RoleDto #######
    RoleDto:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string

    CreateRoleDto:
      type: object
      required:
        - name
      properties:
        name:
          type: string

    ####### Notification #######
    NotificationDto:
      type: object
      required:
        - id
        - title
        - message
        - clickTarget
        - isRead
        - type
        - createdAt
        - organizationId
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        message:
          type: string
        clickTarget:
          type: string
        isRead:
          type: boolean
        recipient:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/UserDto"
        targetRoles:
          type: string
          description: Comma-separated list of target roles (only for role-based notifications)
          nullable: true
        type:
          $ref: "#/components/schemas/NotificationType"
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time

    CreateNotificationDto:
      type: object
      required:
        - title
        - message
        - clickTarget
        - type
        - organizationId
      properties:
        title:
          type: string
        message:
          type: string
        clickTarget:
          type: string
        recipientId:
          type: string
          description: Keycloak ID of the recipient user. If not provided, notification will be role-based or organization-wide.
          nullable: true
        targetRoles:
          type: array
          items:
            type: string
          description: List of roles to send notification to. If both recipientId and targetRoles are null, notification will be sent to all organization members.
          nullable: true
        type:
          $ref: "#/components/schemas/NotificationType"
        organizationId:
          type: string
          description: The organization ID for this notification

    PagedNotificationDto:
      type: object
      allOf:
        - $ref: "#/components/schemas/Page"
      required:
        - content
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/NotificationDto"

    NotificationType:
      type: string
      enum:
        - INFO
        - WARNING
        - ERROR

    ####### FileDto #######
    FileDto:
      type: object
      required:
        - id
        - name
        - file
        - createdAt
        - modifiedAt
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        file:
          type: string
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time

    UploadFileDto:
      type: object
      required:
        - name
        - file
      properties:
        name:
          type: string
        file:
          type: string
          format: binary

    ####### Miscellaneous #######
    ProcessingPurpose:
      type: string
      enum:
        - SYSTEM_OPERATION
        - BUSINESS_PROCESS
        - DATA_ANALYSIS
        - NONE

    EmployeeDataCategory:
      type: string
      enum:
        - NON_CRITICAL
        - REVIEW_REQUIRED
        - SENSITIVE
        - NONE

    ComplianceStatus:
      type: string
      enum:
        - NON_CRITICAL
        - WARNING
        - CRITICAL

    ApplicationFormStatus:
      type: string
      enum:
        - DRAFT
        - SUBMITTED
        - APPROVED
        - REJECTED
        - SIGNED

    ####### Supporting components #######
    Page:
      type: object
      required:
        - number
        - size
        - numberOfElements
        - last
        - totalPages
        - first
        - totalElements
        - empty
      properties:
        number:
          type: integer
          format: int32
          example: 0
        size:
          type: integer
          format: int32
          example: 100
        numberOfElements:
          type: integer
          format: int32
          example: 0
        last:
          type: boolean
          example: true
        totalPages:
          type: integer
          format: int32
          example: 0
        first:
          type: boolean
          example: true
        totalElements:
          type: integer
          format: int64
          example: 0
        empty:
          type: boolean
          example: true