From 0660117c07fa726d545634a20cb0a048a2717987 Mon Sep 17 00:00:00 2001
From: "zero@thinky" <shinyzero0@gmail.com>
Date: Sat, 4 Apr 2026 16:50:25 +0300
Subject: [PATCH] docs(backend): add swag to jobs

---
 backend/internal/handlers/jobs.go | 47 +++++++++++++++++++------------
 1 file changed, 29 insertions(+), 18 deletions(-)

diff --git a/backend/internal/handlers/jobs.go b/backend/internal/handlers/jobs.go
index b4f63e1..c26d26c 100644
--- a/backend/internal/handlers/jobs.go
+++ b/backend/internal/handlers/jobs.go
@@ -2,6 +2,7 @@ package handlers
 
 import (
 	"fmt"
+	"net/http"
 
 	"gitea.d3m0k1d.ru/d3m0k1d/HellreigN/backend/internal/grpcsrv/commander"
 	"gitea.d3m0k1d.ru/d3m0k1d/HellreigN/backend/internal/models"
@@ -18,21 +19,39 @@ func NewJobsHandlers(cmder *commander.Commander, svc *service.ScriptService) Job
 	return JobsHandlers{cmder: cmder, svc: svc}
 }
 
+type AddJobIn struct {
+	Command       string  `json:"command" binding:"required"`
+	InterpreterID int64   `json:"interpreter_id"`
+	Stdin         *string `json:"stdin"`
+	AgentID       string  `json:"agent_id" binding:"required"`
+}
+type AddJobOut struct {
+	ID      int64    `json:"id"`
+	Command []string `json:"command"`
+	Stdin   *string  `json:"stdin"`
+	Stdout  string   `json:"stdout"`
+	Stderr  string   `json:"stderr"`
+	Status  int32    `json:"status"`
+}
+
+// AddJob creates and executes a job on a target agent.
+// @Summary Create and run a job on an agent
+// @Description Sends a command to the specified agent, waits for execution, and returns the result
+// @Tags jobs
+// @Accept json
+// @Produce json
+// @Param body body AddJobIn true "Job request"
+// @Success 201 {object} AddJobOut
+// @Router /jobs [post]
 func (self *JobsHandlers) AddJob(c *gin.Context) {
 	err := func() error {
-		type In struct {
-			Command       string  `json:"command"`
-			InterpreterID int64   `json:"interpreter_id"`
-			Stdin         *string `json:"stdin"`
-			AID           string  `json:"agent_id"`
-		}
-		var in In
+		var in AddJobIn
 		if err := c.Bind(&in); err != nil {
 			return err
 		}
-		agent, ok := self.cmder.GetAgent(in.AID)
+		agent, ok := self.cmder.GetAgent(in.AgentID)
 		if !ok {
-			c.Status(404)
+			c.Status(http.StatusNotFound)
 			return fmt.Errorf("agent not found")
 		}
 
@@ -58,15 +77,7 @@ func (self *JobsHandlers) AddJob(c *gin.Context) {
 		if err != nil {
 			return err
 		}
-		type Out struct {
-			ID      int64    `json:"id"`
-			Command []string `json:"command"`
-			Stdin   *string  `json:"stdin"`
-			Stdout  string   `json:"stdout"`
-			Stderr  string   `json:"stderr"`
-			Status  int32    `json:"status"`
-		}
-		c.JSON(201, Out{
+		c.JSON(http.StatusCreated, AddJobOut{
 			ID:      job.ID,
 			Command: job.Command,
 			Stdin:   job.Stdin,