rede5/gohorsejobs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

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

Browse source
This commit is contained in:
Tiago Yamamoto 2025-12-24 00:45:48 -03:00
parent 7d4bc253d5
commit 72174b5232
4 changed files with 1686 additions and 471 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

798
backend/docs/docs.go
View file

File diff suppressed because it is too large Load diff

798
backend/docs/swagger.json
View file

File diff suppressed because it is too large Load diff

529
backend/docs/swagger.yaml
View file

@ -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"

30
backend/internal/api/handlers/core_handlers.go
View file

@ -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"
// @Success 200 {object} dto.AuthResponse
// @Param login body object true "Login Credentials"
// @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"
// @Success 200 {object} dto.CompanyResponse
// @Param company body object true "Company Details"
// @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"
// @Success 200 {object} dto.UserResponse
// @Param user body object true "User Details"
// @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"
// @Success 200 {object} dto.UserResponse
// @Param user body object true "User Updates"
// @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"
// @Success 200 {object} dto.UserResponse
// @Param user body object true "Profile Details"
// @Success 200 {object} object
// @Failure 400 {string} string "Invalid Request"
// @Failure 500 {string} string "Internal Server Error"
// @Router /api/v1/users/me/profile [patch]