Add Swagger API documentation for ATSFlare Server with detailed endpoint definitions and models

atsf_server/controller/agent.go

@@ -9,6 +9,16 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// AgentRegister godoc
+// @Summary Register or discover agent node
+// @Tags Agent
+// @Accept json
+// @Produce json
+// @Security AgentTokenAuth
+// @Param payload body service.AgentNodePayload true "Agent node payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/agent/nodes/register [post]
 func AgentRegister(c *gin.Context) {
 	var payload service.AgentNodePayload
 	if err := json.NewDecoder(c.Request.Body).Decode(&payload); err != nil {
@@ -41,6 +51,16 @@ func AgentRegister(c *gin.Context) {
 	})
 }
 
+// AgentHeartbeat godoc
+// @Summary Report agent heartbeat
+// @Tags Agent
+// @Accept json
+// @Produce json
+// @Security AgentTokenAuth
+// @Param payload body service.AgentNodePayload true "Agent heartbeat payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/agent/nodes/heartbeat [post]
 func AgentHeartbeat(c *gin.Context) {
 	var payload service.AgentNodePayload
 	if err := json.NewDecoder(c.Request.Body).Decode(&payload); err != nil {
@@ -74,6 +94,13 @@ func AgentHeartbeat(c *gin.Context) {
 	})
 }
 
+// AgentGetActiveConfig godoc
+// @Summary Get active config for agent
+// @Tags Agent
+// @Produce json
+// @Security AgentTokenAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/agent/config-versions/active [get]
 func AgentGetActiveConfig(c *gin.Context) {
 	config, err := service.GetActiveConfigForAgent()
 	if err != nil {
@@ -90,6 +117,16 @@ func AgentGetActiveConfig(c *gin.Context) {
 	})
 }
 
+// AgentReportApplyLog godoc
+// @Summary Report agent apply result
+// @Tags Agent
+// @Accept json
+// @Produce json
+// @Security AgentTokenAuth
+// @Param payload body service.ApplyLogPayload true "Apply log payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/agent/apply-logs [post]
 func AgentReportApplyLog(c *gin.Context) {
 	var payload service.ApplyLogPayload
 	if err := json.NewDecoder(c.Request.Body).Decode(&payload); err != nil {
@@ -118,6 +155,13 @@ func AgentReportApplyLog(c *gin.Context) {
 	})
 }
 
+// GetNodes godoc
+// @Summary List nodes
+// @Tags Nodes
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/nodes/ [get]
 func GetNodes(c *gin.Context) {
 	nodes, err := service.ListNodeViews()
 	if err != nil {
@@ -134,6 +178,14 @@ func GetNodes(c *gin.Context) {
 	})
 }
 
+// GetApplyLogs godoc
+// @Summary List apply logs
+// @Tags ApplyLogs
+// @Produce json
+// @Security BearerAuth
+// @Param node_id query string false "Node ID"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/apply-logs/ [get]
 func GetApplyLogs(c *gin.Context) {
 	logs, err := service.ListApplyLogs(c.Query("node_id"))
 	if err != nil {

atsf_server/controller/config_version.go

@@ -7,6 +7,13 @@ import (
 	"strconv"
 )
 
+// GetConfigVersions godoc
+// @Summary List config versions
+// @Tags ConfigVersions
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/config-versions/ [get]
 func GetConfigVersions(c *gin.Context) {
 	versions, err := service.ListConfigVersions()
 	if err != nil {
@@ -23,6 +30,13 @@ func GetConfigVersions(c *gin.Context) {
 	})
 }
 
+// GetActiveConfigVersion godoc
+// @Summary Get active config version
+// @Tags ConfigVersions
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/config-versions/active [get]
 func GetActiveConfigVersion(c *gin.Context) {
 	version, err := service.GetActiveConfigVersion()
 	if err != nil {
@@ -39,6 +53,13 @@ func GetActiveConfigVersion(c *gin.Context) {
 	})
 }
 
+// PreviewConfigVersion godoc
+// @Summary Preview config rendering
+// @Tags ConfigVersions
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/config-versions/preview [get]
 func PreviewConfigVersion(c *gin.Context) {
 	preview, err := service.PreviewConfigVersion()
 	if err != nil {
@@ -55,6 +76,13 @@ func PreviewConfigVersion(c *gin.Context) {
 	})
 }
 
+// DiffConfigVersion godoc
+// @Summary Diff current draft against active version
+// @Tags ConfigVersions
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/config-versions/diff [get]
 func DiffConfigVersion(c *gin.Context) {
 	diff, err := service.DiffConfigVersion()
 	if err != nil {
@@ -71,6 +99,13 @@ func DiffConfigVersion(c *gin.Context) {
 	})
 }
 
+// PublishConfigVersion godoc
+// @Summary Publish a new config version
+// @Tags ConfigVersions
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/config-versions/publish [post]
 func PublishConfigVersion(c *gin.Context) {
 	username := c.GetString("username")
 	result, err := service.PublishConfigVersion(username)
@@ -88,6 +123,15 @@ func PublishConfigVersion(c *gin.Context) {
 	})
 }
 
+// ActivateConfigVersion godoc
+// @Summary Activate an existing config version
+// @Tags ConfigVersions
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "Version ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/config-versions/{id}/activate [put]
 func ActivateConfigVersion(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil || id == 0 {

atsf_server/controller/managed_domain.go

@@ -9,6 +9,13 @@ import (
 	"strings"
 )
 
+// GetManagedDomains godoc
+// @Summary List managed domains
+// @Tags ManagedDomains
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/managed-domains/ [get]
 func GetManagedDomains(c *gin.Context) {
 	domains, err := service.ListManagedDomains()
 	if err != nil {
@@ -25,6 +32,16 @@ func GetManagedDomains(c *gin.Context) {
 	})
 }
 
+// CreateManagedDomain godoc
+// @Summary Create managed domain
+// @Tags ManagedDomains
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param payload body service.ManagedDomainInput true "Managed domain payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/managed-domains/ [post]
 func CreateManagedDomain(c *gin.Context) {
 	var input service.ManagedDomainInput
 	if err := json.NewDecoder(c.Request.Body).Decode(&input); err != nil {
@@ -49,6 +66,17 @@ func CreateManagedDomain(c *gin.Context) {
 	})
 }
 
+// UpdateManagedDomain godoc
+// @Summary Update managed domain
+// @Tags ManagedDomains
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "Managed domain ID"
+// @Param payload body service.ManagedDomainInput true "Managed domain payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/managed-domains/{id} [put]
 func UpdateManagedDomain(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil || id == 0 {
@@ -81,6 +109,15 @@ func UpdateManagedDomain(c *gin.Context) {
 	})
 }
 
+// DeleteManagedDomain godoc
+// @Summary Delete managed domain
+// @Tags ManagedDomains
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "Managed domain ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/managed-domains/{id} [delete]
 func DeleteManagedDomain(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil || id == 0 {
@@ -103,6 +140,14 @@ func DeleteManagedDomain(c *gin.Context) {
 	})
 }
 
+// MatchManagedDomainCertificate godoc
+// @Summary Match certificate for domain
+// @Tags ManagedDomains
+// @Produce json
+// @Security BearerAuth
+// @Param domain query string true "Domain"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/managed-domains/match [get]
 func MatchManagedDomainCertificate(c *gin.Context) {
 	domain := strings.TrimSpace(c.Query("domain"))
 	result, err := service.MatchManagedDomainCertificate(domain)

atsf_server/controller/misc.go

@@ -9,6 +9,12 @@ import (
 	"net/http"
 )
 
+// GetStatus godoc
+// @Summary Get server status
+// @Tags Public
+// @Produce json
+// @Success 200 {object} map[string]interface{}
+// @Router /api/status [get]
 func GetStatus(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{
 		"success": true,

atsf_server/controller/node.go

@@ -9,6 +9,16 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// CreateNode godoc
+// @Summary Create node
+// @Tags Nodes
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param payload body service.NodeInput true "Node payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/nodes/ [post]
 func CreateNode(c *gin.Context) {
 	var input service.NodeInput
 	if err := json.NewDecoder(c.Request.Body).Decode(&input); err != nil {
@@ -33,6 +43,13 @@ func CreateNode(c *gin.Context) {
 	})
 }
 
+// GetNodeBootstrapToken godoc
+// @Summary Get global discovery token
+// @Tags Nodes
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/nodes/bootstrap-token [get]
 func GetNodeBootstrapToken(c *gin.Context) {
 	bootstrap, err := service.GetNodeBootstrapView()
 	if err != nil {
@@ -49,6 +66,13 @@ func GetNodeBootstrapToken(c *gin.Context) {
 	})
 }
 
+// RotateNodeBootstrapToken godoc
+// @Summary Rotate global discovery token
+// @Tags Nodes
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/nodes/bootstrap-token/rotate [post]
 func RotateNodeBootstrapToken(c *gin.Context) {
 	bootstrap, err := service.RotateGlobalDiscoveryToken()
 	if err != nil {
@@ -65,6 +89,17 @@ func RotateNodeBootstrapToken(c *gin.Context) {
 	})
 }
 
+// UpdateNode godoc
+// @Summary Update node
+// @Tags Nodes
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "Node ID"
+// @Param payload body service.NodeInput true "Node payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/nodes/{id} [put]
 func UpdateNode(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil || id == 0 {
@@ -97,6 +132,15 @@ func UpdateNode(c *gin.Context) {
 	})
 }
 
+// DeleteNode godoc
+// @Summary Delete node
+// @Tags Nodes
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "Node ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/nodes/{id} [delete]
 func DeleteNode(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil || id == 0 {
@@ -119,6 +163,15 @@ func DeleteNode(c *gin.Context) {
 	})
 }
 
+// RequestNodeAgentUpdate godoc
+// @Summary Request agent self-update on node
+// @Tags Nodes
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "Node ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/nodes/{id}/agent-update [post]
 func RequestNodeAgentUpdate(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil || id == 0 {

atsf_server/controller/option.go

@@ -9,6 +9,12 @@ import (
 	"strings"
 )
 
+// GetOptions godoc
+// @Summary List editable options
+// @Tags Options
+// @Produce json
+// @Success 200 {object} map[string]interface{}
+// @Router /api/option/ [get]
 func GetOptions(c *gin.Context) {
 	var options []*model.Option
 	common.OptionMapRWMutex.Lock()
@@ -30,6 +36,15 @@ func GetOptions(c *gin.Context) {
 	return
 }
 
+// UpdateOption godoc
+// @Summary Update option
+// @Tags Options
+// @Accept json
+// @Produce json
+// @Param payload body model.Option true "Option payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/option/ [put]
 func UpdateOption(c *gin.Context) {
 	var option model.Option
 	err := json.NewDecoder(c.Request.Body).Decode(&option)

atsf_server/controller/proxy_route.go

@@ -8,6 +8,13 @@ import (
 	"strconv"
 )
 
+// GetProxyRoutes godoc
+// @Summary List proxy routes
+// @Tags ProxyRoutes
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/proxy-routes/ [get]
 func GetProxyRoutes(c *gin.Context) {
 	routes, err := service.ListProxyRoutes()
 	if err != nil {
@@ -24,6 +31,16 @@ func GetProxyRoutes(c *gin.Context) {
 	})
 }
 
+// CreateProxyRoute godoc
+// @Summary Create proxy route
+// @Tags ProxyRoutes
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param payload body service.ProxyRouteInput true "Proxy route payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/proxy-routes/ [post]
 func CreateProxyRoute(c *gin.Context) {
 	var input service.ProxyRouteInput
 	if err := json.NewDecoder(c.Request.Body).Decode(&input); err != nil {
@@ -48,6 +65,17 @@ func CreateProxyRoute(c *gin.Context) {
 	})
 }
 
+// UpdateProxyRoute godoc
+// @Summary Update proxy route
+// @Tags ProxyRoutes
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "Route ID"
+// @Param payload body service.ProxyRouteInput true "Proxy route payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/proxy-routes/{id} [put]
 func UpdateProxyRoute(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil || id == 0 {
@@ -80,6 +108,15 @@ func UpdateProxyRoute(c *gin.Context) {
 	})
 }
 
+// DeleteProxyRoute godoc
+// @Summary Delete proxy route
+// @Tags ProxyRoutes
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "Route ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/proxy-routes/{id} [delete]
 func DeleteProxyRoute(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil || id == 0 {

atsf_server/controller/tls_certificate.go

@@ -8,6 +8,13 @@ import (
 	"strconv"
 )
 
+// GetTLSCertificates godoc
+// @Summary List TLS certificates
+// @Tags TLSCertificates
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} map[string]interface{}
+// @Router /api/tls-certificates/ [get]
 func GetTLSCertificates(c *gin.Context) {
 	certificates, err := service.ListTLSCertificates()
 	if err != nil {
@@ -24,6 +31,16 @@ func GetTLSCertificates(c *gin.Context) {
 	})
 }
 
+// CreateTLSCertificate godoc
+// @Summary Create TLS certificate from PEM
+// @Tags TLSCertificates
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param payload body service.TLSCertificateInput true "TLS certificate payload"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/tls-certificates/ [post]
 func CreateTLSCertificate(c *gin.Context) {
 	var input service.TLSCertificateInput
 	if err := json.NewDecoder(c.Request.Body).Decode(&input); err != nil {
@@ -48,6 +65,19 @@ func CreateTLSCertificate(c *gin.Context) {
 	})
 }
 
+// ImportTLSCertificateFile godoc
+// @Summary Import TLS certificate from files
+// @Tags TLSCertificates
+// @Accept multipart/form-data
+// @Produce json
+// @Security BearerAuth
+// @Param name formData string true "Certificate name"
+// @Param remark formData string false "Remark"
+// @Param cert_file formData file true "Certificate file"
+// @Param key_file formData file true "Private key file"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/tls-certificates/import-file [post]
 func ImportTLSCertificateFile(c *gin.Context) {
 	name := c.PostForm("name")
 	remark := c.PostForm("remark")
@@ -82,6 +112,15 @@ func ImportTLSCertificateFile(c *gin.Context) {
 	})
 }
 
+// DeleteTLSCertificate godoc
+// @Summary Delete TLS certificate
+// @Tags TLSCertificates
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "Certificate ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]interface{}
+// @Router /api/tls-certificates/{id} [delete]
 func DeleteTLSCertificate(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil || id == 0 {

atsf_server/controller/update.go

@@ -22,6 +22,12 @@ type latestReleaseResponse struct {
 	PublishedAt string `json:"published_at"`
 }
 
+// GetLatestRelease godoc
+// @Summary Get latest GitHub release
+// @Tags Update
+// @Produce json
+// @Success 200 {object} map[string]interface{}
+// @Router /api/update/latest-release [get]
 func GetLatestRelease(c *gin.Context) {
 	req, err := http.NewRequestWithContext(c.Request.Context(), http.MethodGet, latestReleaseURL, nil)
 	if err != nil {