docs(backend): update Swagger annotations for admin and core handlers

backend/docs/swagger.yaml

@@ -1,23 +1,5 @@
 basePath: /
 definitions:
-  dto.AuthResponse:
-    properties:
-      token:
-        type: string
-      user:
-        $ref: '#/definitions/dto.UserResponse'
-    type: object
-  dto.CompanyResponse:
-    properties:
-      created_at:
-        type: string
-      id:
-        type: string
-      name:
-        type: string
-      status:
-        type: string
-    type: object
   dto.CreateApplicationRequest:
     properties:
       documents:
@@ -26,7 +8,7 @@ definitions:
       email:
         type: string
       jobId:
-        type: integer
+        type: string
       lineId:
         type: string
       message:
@@ -38,46 +20,12 @@ definitions:
       resumeUrl:
         type: string
       userId:
-        type: integer
+        type: string
       whatsapp:
         type: string
     required:
     - jobId
     type: object
-  dto.CreateCompanyRequest:
-    properties:
-      address:
-        type: string
-      cityId:
-        type: integer
-      description:
-        type: string
-      document:
-        type: string
-      email:
-        type: string
-      logoUrl:
-        type: string
-      name:
-        maxLength: 255
-        minLength: 3
-        type: string
-      phone:
-        type: string
-      regionId:
-        type: integer
-      slug:
-        maxLength: 255
-        minLength: 3
-        type: string
-      type:
-        type: string
-      website:
-        type: string
-    required:
-    - name
-    - slug
-    type: object
   dto.CreateJobRequest:
     properties:
       benefits:
@@ -86,7 +34,15 @@ definitions:
       cityId:
         type: integer
       companyId:
-        type: integer
+        type: string
+      currency:
+        enum:
+        - BRL
+        - USD
+        - EUR
+        - GBP
+        - JPY
+        type: string
       description:
         minLength: 20
         type: string
@@ -96,6 +52,10 @@ definitions:
         - part-time
         - dispatch
         - contract
+        - temporary
+        - training
+        - voluntary
+        - permanent
         type: string
       languageLevel:
         type: string
@@ -113,6 +73,8 @@ definitions:
       salaryType:
         enum:
         - hourly
+        - daily
+        - weekly
         - monthly
         - yearly
         type: string
@@ -121,6 +83,12 @@ definitions:
         - draft
         - open
         - closed
+        - review
+        - published
+        - paused
+        - expired
+        - archived
+        - reported
         type: string
       title:
         maxLength: 255
@@ -135,32 +103,6 @@ definitions:
     - description
     - title
     type: object
-  dto.CreateUserRequest:
-    properties:
-      email:
-        type: string
-      name:
-        type: string
-      password:
-        type: string
-      roles:
-        description: e.g. ["RECRUITER"]
-        items:
-          type: string
-        type: array
-    type: object
-  dto.LoginRequest:
-    properties:
-      identifier:
-        minLength: 3
-        type: string
-      password:
-        minLength: 8
-        type: string
-    required:
-    - identifier
-    - password
-    type: object
   dto.PaginatedResponse:
     properties:
       data: {}
@@ -198,6 +140,14 @@ definitions:
         type: object
       cityId:
         type: integer
+      currency:
+        enum:
+        - BRL
+        - USD
+        - EUR
+        - GBP
+        - JPY
+        type: string
       description:
         minLength: 20
         type: string
@@ -207,6 +157,10 @@ definitions:
         - part-time
         - dispatch
         - contract
+        - temporary
+        - training
+        - voluntary
+        - permanent
         type: string
       languageLevel:
         type: string
@@ -224,6 +178,8 @@ definitions:
       salaryType:
         enum:
         - hourly
+        - daily
+        - weekly
         - monthly
         - yearly
         type: string
@@ -232,6 +188,12 @@ definitions:
         - draft
         - open
         - closed
+        - review
+        - published
+        - paused
+        - expired
+        - archived
+        - reported
         type: string
       title:
         maxLength: 255
@@ -242,23 +204,6 @@ definitions:
       workingHours:
         type: string
     type: object
-  dto.UserResponse:
-    properties:
-      created_at:
-        type: string
-      email:
-        type: string
-      id:
-        type: string
-      name:
-        type: string
-      roles:
-        items:
-          type: string
-        type: array
-      status:
-        type: string
-    type: object
   handlers.DownloadURLRequest:
     properties:
       key:
@@ -306,9 +251,9 @@ definitions:
       email:
         type: string
       id:
-        type: integer
+        type: string
       jobId:
-        type: integer
+        type: string
       lineId:
         type: string
       message:
@@ -330,7 +275,7 @@ definitions:
         type: string
       userId:
         description: NULL for guest applications
-        type: integer
+        type: string
       whatsapp:
         type: string
     type: object
@@ -344,19 +289,22 @@ definitions:
       cityId:
         type: integer
       companyId:
-        type: integer
+        type: string
       createdAt:
         description: Metadata
         type: string
       createdBy:
-        type: integer
+        type: string
+      currency:
+        description: BRL, USD, EUR, GBP, JPY
+        type: string
       description:
         type: string
       employmentType:
         description: Employment
         type: string
       id:
-        type: integer
+        type: string
       isFeatured:
         description: Featured job flag
         type: boolean
@@ -378,7 +326,7 @@ definitions:
         description: Salary
         type: number
       salaryType:
-        description: hourly, monthly, yearly
+        description: hourly, daily, weekly, monthly, yearly
         type: string
       status:
         description: Status
@@ -391,9 +339,66 @@ definitions:
       visaSupport:
         description: Visa & Language
         type: boolean
+      workMode:
+        description: onsite, hybrid, remote
+        type: string
       workingHours:
         type: string
     type: object
+  models.Notification:
+    properties:
+      createdAt:
+        type: string
+      id:
+        type: string
+      link:
+        type: string
+      message:
+        type: string
+      readAt:
+        type: string
+      title:
+        type: string
+      type:
+        description: info, success, warning, error
+        type: string
+      updatedAt:
+        type: string
+      userId:
+        type: integer
+    type: object
+  models.Ticket:
+    properties:
+      createdAt:
+        type: string
+      id:
+        type: string
+      priority:
+        description: low, medium, high
+        type: string
+      status:
+        description: open, in_progress, closed
+        type: string
+      subject:
+        type: string
+      updatedAt:
+        type: string
+      userId:
+        type: integer
+    type: object
+  models.TicketMessage:
+    properties:
+      createdAt:
+        type: string
+      id:
+        type: string
+      message:
+        type: string
+      ticketId:
+        type: string
+      userId:
+        type: integer
+    type: object
 info:
   contact: {}
   description: API for GoHorseJobs recruitment platform.
@@ -536,14 +541,14 @@ paths:
         name: login
         required: true
         schema:
-          $ref: '#/definitions/dto.LoginRequest'
+          type: object
       produces:
       - application/json
       responses:
         "200":
           description: OK
           schema:
-            $ref: '#/definitions/dto.AuthResponse'
+            type: object
         "400":
           description: Invalid Request
           schema:
@@ -567,7 +572,7 @@ paths:
           description: OK
           schema:
             items:
-              $ref: '#/definitions/dto.CompanyResponse'
+              type: object
             type: array
         "500":
           description: Internal Server Error
@@ -586,14 +591,14 @@ paths:
         name: company
         required: true
         schema:
-          $ref: '#/definitions/dto.CreateCompanyRequest'
+          type: object
       produces:
       - application/json
       responses:
         "200":
           description: OK
           schema:
-            $ref: '#/definitions/dto.CompanyResponse'
+            type: object
         "400":
           description: Invalid Request
           schema:
@@ -759,6 +764,77 @@ paths:
       summary: Update a job
       tags:
       - Jobs
+  /api/v1/notifications:
+    get:
+      consumes:
+      - application/json
+      description: Returns a list of notifications for the current user.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            items:
+              $ref: '#/definitions/models.Notification'
+            type: array
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: List Notifications
+      tags:
+      - Notifications
+  /api/v1/notifications/{id}/read:
+    patch:
+      consumes:
+      - application/json
+      description: Marks a notification as read.
+      parameters:
+      - description: Notification ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: Marked as read
+          schema:
+            type: string
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: Mark Notification Read
+      tags:
+      - Notifications
+  /api/v1/notifications/read-all:
+    patch:
+      consumes:
+      - application/json
+      description: Marks all notifications as read.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: All marked as read
+          schema:
+            type: string
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: Mark All Notifications Read
+      tags:
+      - Notifications
   /api/v1/storage/download-url:
     post:
       consumes:
@@ -852,17 +928,139 @@ paths:
       summary: Generate upload URL
       tags:
       - Storage
+  /api/v1/support/tickets:
+    get:
+      consumes:
+      - application/json
+      description: Returns a list of tickets for the current user.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            items:
+              $ref: '#/definitions/models.Ticket'
+            type: array
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: List Tickets
+      tags:
+      - Support
+    post:
+      consumes:
+      - application/json
+      description: Creates a new support ticket.
+      parameters:
+      - description: Ticket Details
+        in: body
+        name: ticket
+        required: true
+        schema:
+          type: object
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/models.Ticket'
+        "400":
+          description: Invalid Request
+          schema:
+            type: string
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: Create Ticket
+      tags:
+      - Support
+  /api/v1/support/tickets/{id}:
+    get:
+      consumes:
+      - application/json
+      description: Returns ticket details and chat history.
+      parameters:
+      - description: Ticket ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            type: object
+        "404":
+          description: Not Found
+          schema:
+            type: string
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: Get Ticket Details
+      tags:
+      - Support
+  /api/v1/support/tickets/{id}/messages:
+    post:
+      consumes:
+      - application/json
+      description: Adds a message to an existing ticket.
+      parameters:
+      - description: Ticket ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Message
+        in: body
+        name: message
+        required: true
+        schema:
+          type: object
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/models.TicketMessage'
+        "400":
+          description: Invalid Request
+          schema:
+            type: string
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: Add Ticket Message
+      tags:
+      - Support
   /api/v1/users:
     get:
       consumes:
       - application/json
       description: Returns a list of users belonging to the authenticated tenant.
       parameters:
-      - description: Page number (default: 1)
+      - description: 'Page number (default: 1)'
         in: query
         name: page
         type: integer
-      - description: Items per page (default: 10, max: 100)
+      - description: 'Items per page (default: 10, max: 100)'
         in: query
         name: limit
         type: integer
@@ -872,7 +1070,7 @@ paths:
         "200":
           description: OK
           schema:
-            $ref: '#/definitions/dto.PaginatedResponse'
+            type: object
         "403":
           description: Forbidden
           schema:
@@ -896,14 +1094,14 @@ paths:
         name: user
         required: true
         schema:
-          $ref: '#/definitions/dto.CreateUserRequest'
+          type: object
       produces:
       - application/json
       responses:
         "200":
           description: OK
           schema:
-            $ref: '#/definitions/dto.UserResponse'
+            type: object
         "400":
           description: Invalid Request
           schema:
@@ -952,4 +1150,105 @@ paths:
       summary: Delete User
       tags:
       - Users
+    patch:
+      consumes:
+      - application/json
+      description: Updates user details (Name, Email, Active Status)
+      parameters:
+      - description: User ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: User Updates
+        in: body
+        name: user
+        required: true
+        schema:
+          type: object
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            type: object
+        "403":
+          description: Forbidden
+          schema:
+            type: string
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: Update User
+      tags:
+      - Users
+  /api/v1/users/me/avatar:
+    post:
+      consumes:
+      - multipart/form-data
+      description: Uploads a profile picture for the current user.
+      parameters:
+      - description: Avatar File
+        in: formData
+        name: file
+        required: true
+        type: file
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties:
+              type: string
+            type: object
+        "400":
+          description: Invalid Request
+          schema:
+            type: string
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: Upload Avatar
+      tags:
+      - Users
+  /api/v1/users/me/profile:
+    patch:
+      consumes:
+      - application/json
+      description: Updates the current user's profile.
+      parameters:
+      - description: Profile Details
+        in: body
+        name: user
+        required: true
+        schema:
+          type: object
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            type: object
+        "400":
+          description: Invalid Request
+          schema:
+            type: string
+        "500":
+          description: Internal Server Error
+          schema:
+            type: string
+      security:
+      - BearerAuth: []
+      summary: Update My Profile
+      tags:
+      - Users
 swagger: "2.0"

backend/internal/api/handlers/core_handlers.go

@@ -51,8 +51,8 @@ func NewCoreHandlers(l *auth.LoginUseCase, reg *auth.RegisterCandidateUseCase, c
 // @Tags         Auth
 // @Accept       json
 // @Produce      json
-// @Param        login  body      dto.LoginRequest  true  "Login Credentials"
+// @Param        login  body      object  true  "Login Credentials"
-// @Success      200    {object}  dto.AuthResponse
+// @Success      200    {object}  object
 // @Failure      400    {string}  string "Invalid Request"
 // @Failure      401    {string}  string "Unauthorized"
 // @Router       /api/v1/auth/login [post]
@@ -121,8 +121,8 @@ func (h *CoreHandlers) RegisterCandidate(w http.ResponseWriter, r *http.Request)
 // @Tags         Companies
 // @Accept       json
 // @Produce      json
-// @Param        company  body      dto.CreateCompanyRequest  true  "Company Details"
+// @Param        company  body      object  true  "Company Details"
-// @Success      200      {object}  dto.CompanyResponse
+// @Success      200      {object}  object
 // @Failure      400      {string}  string "Invalid Request"
 // @Failure      500      {string}  string "Internal Server Error"
 // @Router       /api/v1/companies [post]
@@ -149,7 +149,7 @@ func (h *CoreHandlers) CreateCompany(w http.ResponseWriter, r *http.Request) {
 // @Tags         Companies
 // @Accept       json
 // @Produce      json
-// @Success      200      {array}   dto.CompanyResponse
+// @Success      200      {array}   object
 // @Failure      500      {string}  string "Internal Server Error"
 // @Router       /api/v1/companies [get]
 func (h *CoreHandlers) ListCompanies(w http.ResponseWriter, r *http.Request) {
@@ -170,8 +170,8 @@ func (h *CoreHandlers) ListCompanies(w http.ResponseWriter, r *http.Request) {
 // @Accept       json
 // @Produce      json
 // @Security     BearerAuth
-// @Param        user  body      dto.CreateUserRequest  true  "User Details"
+// @Param        user  body      object  true  "User Details"
-// @Success      200   {object}  dto.UserResponse
+// @Success      200   {object}  object
 // @Failure      400   {string}  string "Invalid Request"
 // @Failure      403   {string}  string "Forbidden"
 // @Failure      500   {string}  string "Internal Server Error"
@@ -209,7 +209,7 @@ func (h *CoreHandlers) CreateUser(w http.ResponseWriter, r *http.Request) {
 // @Security     BearerAuth
 // @Param        page   query     int   false  "Page number (default: 1)"
 // @Param        limit  query     int   false  "Items per page (default: 10, max: 100)"
-// @Success      200   {object}  dto.PaginatedResponse
+// @Success      200   {object}  object
 // @Failure      403   {string}  string "Forbidden"
 // @Failure      500   {string}  string "Internal Server Error"
 // @Router       /api/v1/users [get]
@@ -280,8 +280,8 @@ func (h *CoreHandlers) DeleteUser(w http.ResponseWriter, r *http.Request) {
 // @Produce      json
 // @Security     BearerAuth
 // @Param        id    path      string                 true  "User ID"
-// @Param        user  body      dto.UpdateUserRequest  true  "User Updates"
+// @Param        user  body      object  true  "User Updates"
-// @Success      200   {object}  dto.UserResponse
+// @Success      200   {object}  object
 // @Failure      403   {string}  string "Forbidden"
 // @Failure      500   {string}  string "Internal Server Error"
 // @Router       /api/v1/users/{id} [patch]
@@ -475,7 +475,7 @@ func (h *CoreHandlers) MarkAllNotificationsAsRead(w http.ResponseWriter, r *http
 // @Accept       json
 // @Produce      json
 // @Security     BearerAuth
-// @Param        ticket  body      dto.CreateTicketRequest  true  "Ticket Details"
+// @Param        ticket  body      object  true  "Ticket Details"
 // @Success      201     {object}  models.Ticket
 // @Failure      400     {string}  string "Invalid Request"
 // @Failure      500     {string}  string "Internal Server Error"
@@ -558,7 +558,7 @@ func (h *CoreHandlers) ListTickets(w http.ResponseWriter, r *http.Request) {
 // @Produce      json
 // @Security     BearerAuth
 // @Param        id    path      string  true  "Ticket ID"
-// @Success      200   {object}  dto.TicketDetailsResponse
+// @Success      200   {object}  object
 // @Failure      404   {string}  string "Not Found"
 // @Failure      500   {string}  string "Internal Server Error"
 // @Router       /api/v1/support/tickets/{id} [get]
@@ -607,7 +607,7 @@ func (h *CoreHandlers) GetTicket(w http.ResponseWriter, r *http.Request) {
 // @Produce      json
 // @Security     BearerAuth
 // @Param        id       path      string             true  "Ticket ID"
-// @Param        message  body      dto.MessageRequest true  "Message"
+// @Param        message  body      object true  "Message"
 // @Success      201      {object}  models.TicketMessage
 // @Failure      400      {string}  string "Invalid Request"
 // @Failure      500      {string}  string "Internal Server Error"
@@ -659,8 +659,8 @@ func (h *CoreHandlers) AddMessage(w http.ResponseWriter, r *http.Request) {
 // @Accept       json
 // @Produce      json
 // @Security     BearerAuth
-// @Param        user  body      dto.UpdateUserRequest  true  "Profile Details"
+// @Param        user  body      object  true  "Profile Details"
-// @Success      200   {object}  dto.UserResponse
+// @Success      200   {object}  object
 // @Failure      400   {string}  string "Invalid Request"
 // @Failure      500   {string}  string "Internal Server Error"
 // @Router       /api/v1/users/me/profile [patch]