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

docs: update backend api docs and swagger

Browse source
This commit is contained in:
Tiago Yamamoto 2025-12-28 00:29:34 -03:00
parent 2217755478
commit b79566aad7
5 changed files with 2161 additions and 420 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
backend/BACKEND.md
View file

@ -137,35 +137,63 @@ Este workflow é disparado automaticamente ao realizar um push para o branch `de
---
## 📡 Endpoints Principais
## 📡 Endpoints (API Reference)
### Helper & System
| Recurso | Método | Endpoint | Descrição |
|---------|--------|----------|-----------|
| Health | `GET` | `/health` | Health Check |
| Docs | `GET` | `/docs/*` | Swagger UI |
| Settings| `GET` | `/api/v1/system/settings/{key}` | Obter configurações públicas |
### 🔐 Auth & Core
| Método | Endpoint | Descrição | Roles |
|--------|----------|-----------|-------|
| `POST` | `/api/v1/auth/login` | Autenticação de usuário | Public |
| `POST` | `/api/v1/auth/register` | Registro de Candidato | Public |
| `POST` | `/api/v1/auth/register/company` | Registro de Empresa | Public |
| `GET` | `/api/v1/users/me` | Dados do usuário logado | Auth |
| `PATCH` | `/api/v1/users/me/profile` | Atualizar perfil | Auth |
| `GET` | `/api/v1/notifications` | Listar notificações | Auth |
| `POST` | `/api/v1/tokens` | Salvar token FCM | Auth |
### Auth & Usuários
| Recurso | Método | Endpoint | Roles |
|---------|--------|----------|-------|
| Login | `POST` | `/api/v1/auth/login` | Public |
| Me | `GET` | `/api/v1/users/me` | Auth |
| Profile | `PATCH`| `/api/v1/users/me/profile` | Auth |
### 💼 Jobs (Vagas)
| Método | Endpoint | Descrição | Roles |
|--------|----------|-----------|-------|
| `GET` | `/api/v1/jobs` | Listar vagas (filtros) | Public |
| `GET` | `/api/v1/jobs/{id}` | Detalhes da vaga | Public |
| `POST` | `/api/v1/jobs` | Criar nova vaga | Recruiter |
| `PUT` | `/api/v1/jobs/{id}` | Editar vaga | Recruiter |
| `DELETE` | `/api/v1/jobs/{id}` | Remover vaga | Recruiter |
### Tickets & Suporte (Novo)
| Recurso | Método | Endpoint | Roles |
|---------|--------|----------|-------|
| Listar | `GET` | `/api/v1/support/tickets` | Auth |
| Criar | `POST` | `/api/v1/support/tickets` | Auth |
| Mensagem| `POST` | `/api/v1/support/tickets/{id}/messages`| Auth |
### 📝 Applications (Candidaturas)
| Método | Endpoint | Descrição | Roles |
|--------|----------|-----------|-------|
| `POST` | `/api/v1/applications` | Candidatar-se a uma vaga | Candidate |
| `GET` | `/api/v1/applications` | Minhas candidaturas | Auth |
| `GET` | `/api/v1/applications/{id}` | Detalhes da candidatura | Auth |
| `PUT` | `/api/v1/applications/{id}/status` | Atualizar status | Recruiter |
| `DELETE` | `/api/v1/applications/{id}` | Desistir/Remover | Auth |
### Admin & Credenciais (Novo)
| Recurso | Método | Endpoint | Roles |
|---------|--------|----------|-------|
| Credentials | `GET` | `/api/v1/system/credentials` | Admin |
| Credentials | `POST` | `/api/v1/system/credentials` | Admin |
| Purge Cache | `POST` | `/api/v1/system/cloudflare/purge`| Admin |
### 🎫 Support (Tickets)
| Método | Endpoint | Descrição | Roles |
|--------|----------|-----------|-------|
| `GET` | `/api/v1/support/tickets` | Meus tickets de suporte | Auth |
| `POST` | `/api/v1/support/tickets` | Abrir novo ticket | Auth |
| `GET` | `/api/v1/support/tickets/{id}` | Ver conversa do ticket | Auth |
| `POST` | `/api/v1/support/tickets/{id}/messages` | Enviar mensagem | Auth |
| `PATCH` | `/api/v1/support/tickets/{id}/close` | Fechar ticket | Auth |
### 💬 Chat & Locais
| Método | Endpoint | Descrição | Roles |
|--------|----------|-----------|-------|
| `GET` | `/api/v1/conversations` | Listar conversas | Auth |
| `GET` | `/api/v1/conversations/{id}/messages` | Ver mensagens | Auth |
| `POST` | `/api/v1/conversations/{id}/messages` | Enviar mensagem | Auth |
| `GET` | `/api/v1/locations/search` | Buscar cidade/estado | Public |
### 🛡️ Admin & System
| Método | Endpoint | Descrição | Roles |
|--------|----------|-----------|-------|
| `GET` | `/api/v1/users` | Listar todos usuários | Admin |
| `GET` | `/api/v1/jobs/moderation` | Moderação de vagas | Admin |
| `GET` | `/api/v1/system/credentials` | Ver credenciais (mascaradas) | Admin |
| `POST` | `/api/v1/system/credentials` | Salvar credencial | Admin |
| `POST` | `/api/v1/system/cloudflare/purge` | Limpar cache CDN | Admin |
| `GET` | `/api/v1/admin/email-templates` | Gerenciar emails | Admin |
---

935
backend/docs/docs.go
View file

File diff suppressed because it is too large Load diff

935
backend/docs/swagger.json
View file

File diff suppressed because it is too large Load diff

629
backend/docs/swagger.yaml
View file

@ -1,6 +1,13 @@
basePath: /
definitions:
dto.CreateApplicationRequest:
github_com_rede5_gohorsejobs_backend_internal_core_dto.SaveFCMTokenRequest:
properties:
platform:
type: string
token:
type: string
type: object
github_com_rede5_gohorsejobs_backend_internal_dto.CreateApplicationRequest:
properties:
documents:
additionalProperties: true
@ -26,7 +33,7 @@ definitions:
required:
- jobId
type: object
dto.CreateJobRequest:
github_com_rede5_gohorsejobs_backend_internal_dto.CreateJobRequest:
properties:
benefits:
additionalProperties: true
@ -42,6 +49,11 @@ definitions:
- EUR
- GBP
- JPY
- CNY
- AED
- CAD
- AUD
- CHF
type: string
description:
minLength: 20
@ -70,6 +82,8 @@ definitions:
type: number
salaryMin:
type: number
salaryNegotiable:
type: boolean
salaryType:
enum:
- hourly
@ -103,13 +117,13 @@ definitions:
- description
- title
type: object
dto.PaginatedResponse:
github_com_rede5_gohorsejobs_backend_internal_dto.PaginatedResponse:
properties:
data: {}
pagination:
$ref: '#/definitions/dto.Pagination'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_dto.Pagination'
type: object
dto.Pagination:
github_com_rede5_gohorsejobs_backend_internal_dto.Pagination:
properties:
limit:
type: integer
@ -118,7 +132,7 @@ definitions:
total:
type: integer
type: object
dto.UpdateApplicationStatusRequest:
github_com_rede5_gohorsejobs_backend_internal_dto.UpdateApplicationStatusRequest:
properties:
notes:
type: string
@ -133,7 +147,42 @@ definitions:
required:
- status
type: object
dto.UpdateJobRequest:
github_com_rede5_gohorsejobs_backend_internal_dto.UpdateCompanyRequest:
properties:
active:
type: boolean
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
verified:
type: boolean
website:
type: string
type: object
github_com_rede5_gohorsejobs_backend_internal_dto.UpdateJobRequest:
properties:
benefits:
additionalProperties: true
@ -147,6 +196,11 @@ definitions:
- EUR
- GBP
- JPY
- CNY
- AED
- CAD
- AUD
- CHF
type: string
description:
minLength: 20
@ -175,6 +229,8 @@ definitions:
type: number
salaryMin:
type: number
salaryNegotiable:
type: boolean
salaryType:
enum:
- hourly
@ -204,87 +260,14 @@ definitions:
workingHours:
type: string
type: object
dto.User:
properties:
companyId:
type: string
createdAt:
type: string
email:
type: string
id:
type: string
name:
type: string
role:
type: string
status:
type: string
type: object
handlers.CreateCheckoutRequest:
properties:
cancelUrl:
description: URL after cancel
type: string
jobId:
type: integer
priceId:
description: Stripe Price ID
type: string
successUrl:
description: URL after success
type: string
type: object
handlers.CreateCheckoutResponse:
properties:
checkoutUrl:
type: string
sessionId:
type: string
type: object
handlers.DownloadURLRequest:
properties:
key:
type: string
type: object
handlers.DownloadURLResponse:
properties:
downloadUrl:
type: string
expiresIn:
description: seconds
type: integer
type: object
handlers.UploadURLRequest:
properties:
contentType:
type: string
filename:
type: string
folder:
description: 'Optional: logos, resumes, documents'
type: string
type: object
handlers.UploadURLResponse:
properties:
expiresIn:
description: seconds
type: integer
key:
type: string
publicUrl:
type: string
uploadUrl:
type: string
type: object
models.Application:
github_com_rede5_gohorsejobs_backend_internal_models.Application:
properties:
createdAt:
description: Metadata
type: string
documents:
allOf:
- $ref: '#/definitions/models.JSONMap'
- $ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.JSONMap'
description: Array of {type, url}
email:
type: string
@ -317,13 +300,13 @@ definitions:
whatsapp:
type: string
type: object
models.JSONMap:
github_com_rede5_gohorsejobs_backend_internal_models.JSONMap:
additionalProperties: true
type: object
models.Job:
github_com_rede5_gohorsejobs_backend_internal_models.Job:
properties:
benefits:
$ref: '#/definitions/models.JSONMap'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.JSONMap'
cityId:
type: integer
companyId:
@ -356,13 +339,16 @@ definitions:
type: integer
requirements:
allOf:
- $ref: '#/definitions/models.JSONMap'
- $ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.JSONMap'
description: Requirements & Benefits (JSONB arrays)
salaryMax:
type: number
salaryMin:
description: Salary
type: number
salaryNegotiable:
description: Candidate proposes salary
type: boolean
salaryType:
description: hourly, daily, weekly, monthly, yearly
type: string
@ -383,6 +369,99 @@ definitions:
workingHours:
type: string
type: object
github_com_rede5_gohorsejobs_backend_internal_services.Conversation:
properties:
candidateId:
type: string
companyId:
type: string
id:
type: string
jobId:
type: string
lastMessage:
type: string
lastMessageAt:
type: string
participantAvatar:
type: string
participantName:
type: string
unreadCount:
type: integer
type: object
github_com_rede5_gohorsejobs_backend_internal_services.Message:
properties:
content:
type: string
conversationId:
type: string
createdAt:
type: string
id:
type: string
isMine:
description: Populated by handler/frontend logic
type: boolean
senderId:
type: string
type: object
internal_handlers.CreateCheckoutRequest:
properties:
cancelUrl:
description: URL after cancel
type: string
jobId:
type: integer
priceId:
description: Stripe Price ID
type: string
successUrl:
description: URL after success
type: string
type: object
internal_handlers.CreateCheckoutResponse:
properties:
checkoutUrl:
type: string
sessionId:
type: string
type: object
internal_handlers.DownloadURLRequest:
properties:
key:
type: string
type: object
internal_handlers.DownloadURLResponse:
properties:
downloadUrl:
type: string
expiresIn:
description: seconds
type: integer
type: object
internal_handlers.UploadURLRequest:
properties:
contentType:
type: string
filename:
type: string
folder:
description: 'Optional: logos, resumes, documents'
type: string
type: object
internal_handlers.UploadURLResponse:
properties:
expiresIn:
description: seconds
type: integer
key:
type: string
publicUrl:
type: string
uploadUrl:
type: string
type: object
info:
contact: {}
description: API for GoHorseJobs recruitment platform.
@ -407,7 +486,7 @@ paths:
description: OK
schema:
items:
$ref: '#/definitions/models.Application'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.Application'
type: array
"400":
description: Bad Request
@ -430,14 +509,14 @@ paths:
name: application
required: true
schema:
$ref: '#/definitions/dto.CreateApplicationRequest'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_dto.CreateApplicationRequest'
produces:
- application/json
responses:
"201":
description: Created
schema:
$ref: '#/definitions/models.Application'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.Application'
"400":
description: Bad Request
schema:
@ -492,7 +571,7 @@ paths:
"200":
description: OK
schema:
$ref: '#/definitions/models.Application'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.Application'
"400":
description: Bad Request
schema:
@ -520,14 +599,14 @@ paths:
name: body
required: true
schema:
$ref: '#/definitions/dto.UpdateApplicationStatusRequest'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_dto.UpdateApplicationStatusRequest'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/models.Application'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.Application'
"400":
description: Bad Request
schema:
@ -621,6 +700,30 @@ paths:
tags:
- Companies
/api/v1/companies/{id}:
delete:
description: Deletes a company by ID (admin only)
parameters:
- description: Company ID
in: path
name: id
required: true
type: string
responses:
"204":
description: No Content
"401":
description: Unauthorized
schema:
type: string
"500":
description: Internal Server Error
schema:
type: string
security:
- BearerAuth: []
summary: Delete Company
tags:
- Companies
get:
consumes:
- application/json
@ -645,6 +748,120 @@ paths:
summary: Get Company
tags:
- Companies
patch:
consumes:
- application/json
description: Updates company information by ID (admin only)
parameters:
- description: Company ID
in: path
name: id
required: true
type: string
- description: Company update data
in: body
name: body
required: true
schema:
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_dto.UpdateCompanyRequest'
produces:
- application/json
responses:
"200":
description: OK
schema:
type: object
"400":
description: Invalid Request
schema:
type: string
"401":
description: Unauthorized
schema:
type: string
"500":
description: Internal Server Error
schema:
type: string
security:
- BearerAuth: []
summary: Update Company
tags:
- Companies
/api/v1/conversations:
get:
consumes:
- application/json
description: List chat conversations for candidate or company
produces:
- application/json
responses:
"200":
description: OK
schema:
items:
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_services.Conversation'
type: array
security:
- BearerAuth: []
summary: List Conversations
tags:
- Chat
/api/v1/conversations/{id}/messages:
get:
consumes:
- application/json
description: Get message history for a conversation
parameters:
- description: Conversation ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
items:
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_services.Message'
type: array
security:
- BearerAuth: []
summary: List Messages
tags:
- Chat
post:
consumes:
- application/json
description: Send a message to a conversation
parameters:
- description: Conversation ID
in: path
name: id
required: true
type: string
- description: Message Content
in: body
name: request
required: true
schema:
additionalProperties:
type: string
type: object
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_services.Message'
security:
- BearerAuth: []
summary: Send Message
tags:
- Chat
/api/v1/jobs:
get:
consumes:
@ -673,7 +890,7 @@ paths:
"200":
description: OK
schema:
$ref: '#/definitions/dto.PaginatedResponse'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_dto.PaginatedResponse'
"500":
description: Internal Server Error
schema:
@ -691,14 +908,14 @@ paths:
name: job
required: true
schema:
$ref: '#/definitions/dto.CreateJobRequest'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_dto.CreateJobRequest'
produces:
- application/json
responses:
"201":
description: Created
schema:
$ref: '#/definitions/models.Job'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.Job'
"400":
description: Bad Request
schema:
@ -757,7 +974,7 @@ paths:
"200":
description: OK
schema:
$ref: '#/definitions/models.Job'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.Job'
"400":
description: Bad Request
schema:
@ -784,14 +1001,14 @@ paths:
name: job
required: true
schema:
$ref: '#/definitions/dto.UpdateJobRequest'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_dto.UpdateJobRequest'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/models.Job'
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_models.Job'
"400":
description: Bad Request
schema:
@ -885,14 +1102,14 @@ paths:
name: request
required: true
schema:
$ref: '#/definitions/handlers.CreateCheckoutRequest'
$ref: '#/definitions/internal_handlers.CreateCheckoutRequest'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/handlers.CreateCheckoutResponse'
$ref: '#/definitions/internal_handlers.CreateCheckoutResponse'
"400":
description: Bad Request
schema:
@ -960,14 +1177,14 @@ paths:
name: request
required: true
schema:
$ref: '#/definitions/handlers.DownloadURLRequest'
$ref: '#/definitions/internal_handlers.DownloadURLRequest'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/handlers.DownloadURLResponse'
$ref: '#/definitions/internal_handlers.DownloadURLResponse'
"400":
description: Bad Request
schema:
@ -1021,14 +1238,14 @@ paths:
name: request
required: true
schema:
$ref: '#/definitions/handlers.UploadURLRequest'
$ref: '#/definitions/internal_handlers.UploadURLRequest'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/handlers.UploadURLResponse'
$ref: '#/definitions/internal_handlers.UploadURLResponse'
"400":
description: Bad Request
schema:
@ -1097,6 +1314,34 @@ paths:
tags:
- Support
/api/v1/support/tickets/{id}:
delete:
description: Deletes a support ticket (admin only).
parameters:
- description: Ticket ID
in: path
name: id
required: true
type: string
responses:
"204":
description: No Content
"401":
description: Unauthorized
schema:
type: string
"403":
description: Forbidden
schema:
type: string
"500":
description: Internal Server Error
schema:
type: string
security:
- BearerAuth: []
summary: Delete Ticket
tags:
- Support
get:
consumes:
- application/json
@ -1127,6 +1372,77 @@ paths:
summary: Get Ticket Details
tags:
- Support
patch:
consumes:
- application/json
description: Updates a ticket's status and/or priority.
parameters:
- description: Ticket ID
in: path
name: id
required: true
type: string
- description: Update data (status, priority)
in: body
name: ticket
required: true
schema:
type: object
produces:
- application/json
responses:
"200":
description: OK
schema:
type: object
"400":
description: Invalid Request
schema:
type: string
"401":
description: Unauthorized
schema:
type: string
"500":
description: Internal Server Error
schema:
type: string
security:
- BearerAuth: []
summary: Update Ticket
tags:
- Support
/api/v1/support/tickets/{id}/close:
patch:
consumes:
- application/json
description: Closes a support ticket.
parameters:
- description: Ticket ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
type: object
"401":
description: Unauthorized
schema:
type: string
"500":
description: Internal Server Error
schema:
type: string
security:
- BearerAuth: []
summary: Close Ticket
tags:
- Support
/api/v1/support/tickets/{id}/messages:
post:
consumes:
@ -1164,6 +1480,109 @@ paths:
summary: Add Ticket Message
tags:
- Support
/api/v1/support/tickets/all:
get:
consumes:
- application/json
description: Returns all support tickets for admin review.
parameters:
- description: Filter by status (open, in_progress, closed)
in: query
name: status
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
items:
type: object
type: array
"403":
description: Forbidden
schema:
type: string
"500":
description: Internal Server Error
schema:
type: string
security:
- BearerAuth: []
summary: List All Tickets (Admin)
tags:
- Support
/api/v1/system/credentials:
post:
consumes:
- application/json
description: Saves encrypted credentials payload (e.g. Stripe key encrypted
by Backoffice)
parameters:
- description: Credentials Payload
in: body
name: request
required: true
schema:
additionalProperties:
type: string
type: object
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: Save Credentials
tags:
- System
/api/v1/tokens:
post:
consumes:
- application/json
description: Saves or updates the FCM token for push notifications.
parameters:
- description: FCM Token
in: body
name: request
required: true
schema:
$ref: '#/definitions/github_com_rede5_gohorsejobs_backend_internal_core_dto.SaveFCMTokenRequest'
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: Save FCM Token
tags:
- Notifications
/api/v1/users:
get:
consumes:
@ -1315,7 +1734,7 @@ paths:
"200":
description: OK
schema:
$ref: '#/definitions/dto.User'
type: object
"401":
description: Unauthorized
schema:

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

@ -1035,7 +1035,7 @@ func (h *CoreHandlers) UploadMyAvatar(w http.ResponseWriter, r *http.Request) {
// @Accept json
// @Produce json
// @Security BearerAuth
// @Success 200 {object} dto.User
// @Success 200 {object} object
// @Failure 401 {string} string "Unauthorized"
// @Failure 500 {string} string "Internal Server Error"
// @Router /api/v1/users/me [get]
@ -1046,7 +1046,7 @@ func (h *CoreHandlers) UploadMyAvatar(w http.ResponseWriter, r *http.Request) {
// @Accept json
// @Produce json
// @Security BearerAuth
// @Success 200 {object} dto.User
// @Success 200 {object} object
// @Failure 401 {string} string "Unauthorized"
// @Failure 500 {string} string "Internal Server Error"
// @Router /api/v1/users/me [get]