swagger: make swagger file validated

.github/workflows/docs.yml

@@ -26,11 +26,17 @@ jobs:
       - name: Install Swag
         run: go install github.com/swaggo/swag/cmd/swag@latest
 
+      - name: Install swagger
+        run: go install github.com/go-swagger/go-swagger/cmd/swagger@latest
+
       - name: Generating Docs
         run: |
           export PATH=$PATH:$(go env GOPATH)/bin
           swag i --md docs/ --parseDependency  --parseInternal --outputTypes yaml  --parseDepth 1 --output .
 
+      - name: Validate Swagger File
+        run: swagger validate ./swagger.yaml
+
       - name: Get current timestamp
         id: timestamp
         run: echo "timestamp=$(date +'%Y-%m-%d %H:%M:%S')" >> $GITHUB_OUTPUT

controllers/acls.go

@@ -224,7 +224,7 @@ func getAcls(w http.ResponseWriter, r *http.Request) {
 }
 
 // @Summary     List Egress Acls in a network
-// @Router      /api/v1/acls [get]
+// @Router      /api/v1/acls/egress [get]
 // @Tags        ACL
 // @Accept      json
 // @Success     200 {array} models.SuccessResponse

controllers/dns.go

@@ -51,7 +51,6 @@ func dnsHandlers(r *mux.Router) {
 // @Router      /api/v1/nameserver/global [get]
 // @Tags        Auth
 // @Accept      json
-// @Param       query network string
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -65,7 +64,7 @@ func getGlobalNs(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/nameserver [post]
 // @Tags        DNS
 // @Accept      json
-// @Param       body body models.NameserverReq
+// @Param       body body models.NameserverReq true "Nameserver request body"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -150,7 +149,7 @@ func createNs(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/nameserver [get]
 // @Tags        Auth
 // @Accept      json
-// @Param       query network string
+// @Param       network query string true "Network identifier"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -179,7 +178,7 @@ func listNs(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/nameserver [put]
 // @Tags        Auth
 // @Accept      json
-// @Param       body body models.NameserverReq
+// @Param       body body models.NameserverReq true "Nameserver request body"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -274,7 +273,7 @@ func updateNs(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/nameserver [delete]
 // @Tags        Auth
 // @Accept      json
-// @Param       body body models.Egress
+// @Param       id query string true "Nameserver ID"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -569,6 +568,7 @@ func pushDNS(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/dns/adm/{network}/sync [post]
 // @Tags        DNS
 // @Accept      json
+// @Param       network path string true "Network identifier"
 // @Success     200 {string} string "DNS Sync completed successfully"
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     500 {object} models.ErrorResponse

controllers/egress.go

@@ -29,7 +29,7 @@ func egressHandlers(r *mux.Router) {
 // @Router      /api/v1/egress [post]
 // @Tags        Auth
 // @Accept      json
-// @Param       body body models.Egress
+// @Param       body body models.EgressReq true "Egress request data"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -160,7 +160,7 @@ func createEgress(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/egress [get]
 // @Tags        Auth
 // @Accept      json
-// @Param       query network string
+// @Param       network query string true "Network identifier"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -189,7 +189,7 @@ func listEgress(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/egress [put]
 // @Tags        Auth
 // @Accept      json
-// @Param       body body models.Egress
+// @Param       body body models.EgressReq true "Egress request data"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -348,7 +348,7 @@ func updateEgress(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/egress [delete]
 // @Tags        Auth
 // @Accept      json
-// @Param       body body models.Egress
+// @Param       id query string true "Egress resource ID"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse

controllers/ext_client.go

@@ -61,6 +61,7 @@ func checkIngressExists(nodeID string) bool {
 // @Router      /api/extclients/{network} [get]
 // @Tags        Remote Access Client
 // @Security    oauth2
+// @Param       network path string true "Network ID"
 // @Success     200 {object} models.ExtClient
 // @Failure     500 {object} models.ErrorResponse
 func getNetworkExtClients(w http.ResponseWriter, r *http.Request) {
@@ -111,6 +112,8 @@ func getAllExtClients(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/extclients/{network}/{clientid} [get]
 // @Tags        Remote Access Client
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       clientid path string true "Client ID"
 // @Success     200 {object} models.ExtClient
 // @Failure     500 {object} models.ErrorResponse
 // @Failure     403 {object} models.ErrorResponse
@@ -148,6 +151,9 @@ func getExtClient(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/extclients/{network}/{clientid}/{type} [get]
 // @Tags        Remote Access Client
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       clientid path string true "Client ID"
+// @Param       type path string true "Client config type"
 // @Success     200 {object} models.ExtClient
 // @Failure     500 {object} models.ErrorResponse
 // @Failure     403 {object} models.ErrorResponse
@@ -384,9 +390,10 @@ Endpoint = %s
 }
 
 // @Summary     Get an individual remote access client
-// @Router      /api/extclients/{network}/{clientid}/{type} [get]
+// @Router      /api/v1/client_conf/{network} [get]
 // @Tags        Remote Access Client
 // @Security    oauth2
+// @Param       network path string true "Network ID"
 // @Success     200 {object} models.ExtClient
 // @Failure     500 {object} models.ErrorResponse
 // @Failure     403 {object} models.ErrorResponse
@@ -625,6 +632,8 @@ Endpoint = %s
 // @Router      /api/extclients/{network}/{nodeid} [post]
 // @Tags        Remote Access Client
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       nodeid path string true "Node ID (Ingress Gateway)"
 // @Success     200 {string} string "OK"
 // @Failure     500 {object} models.ErrorResponse
 // @Failure     400 {object} models.ErrorResponse
@@ -834,6 +843,8 @@ func createExtClient(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/extclients/{network}/{clientid} [put]
 // @Tags        Remote Access Client
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       clientid path string true "Client ID"
 // @Success     200 {object} models.ExtClient
 // @Failure     500 {object} models.ErrorResponse
 // @Failure     400 {object} models.ErrorResponse
@@ -956,6 +967,8 @@ func updateExtClient(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/extclients/{network}/{clientid} [delete]
 // @Tags        Remote Access Client
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       clientid path string true "Client ID"
 // @Success     200
 // @Failure     500 {object} models.ErrorResponse
 // @Failure     403 {object} models.ErrorResponse

controllers/files.go

@@ -9,7 +9,8 @@ import (
 // @Summary     Retrieve a file from the file server
 // @Router      /meshclient/files/{filename}  [get]
 // @Tags        Meshclient
-// @Success     200 {body} file "file"
+// @Param       filename path string true "Filename"
+// @Success     200 {file} file "file"
 // @Failure     404 {string} string "404 not found"
 func fileHandlers(r *mux.Router) {
 	r.PathPrefix("/meshclient/files").

controllers/gateway.go

@@ -27,6 +27,8 @@ func gwHandlers(r *mux.Router) {
 // @Router      /api/nodes/{network}/{nodeid}/gateway [post]
 // @Tags        Nodes
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       nodeid path string true "Node ID"
 // @Success     200 {object} models.ApiNode
 // @Failure     500 {object} models.ErrorResponse
 func createGateway(w http.ResponseWriter, r *http.Request) {
@@ -150,6 +152,8 @@ func createGateway(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/nodes/{network}/{nodeid}/gateway [delete]
 // @Tags        Nodes
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       nodeid path string true "Node ID"
 // @Success     200 {object} models.ApiNode
 // @Failure     500 {object} models.ErrorResponse
 func deleteGateway(w http.ResponseWriter, r *http.Request) {

controllers/hosts.go

@@ -1202,6 +1202,7 @@ func getPendingHosts(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/pending_hosts/approve/{id} [post]
 // @Tags        Hosts
 // @Security    oauth
+// @Param       id path string true "Pending Host ID"
 // @Success     200 {array} models.ApiNode
 // @Failure     500 {object} models.ErrorResponse
 func approvePendingHost(w http.ResponseWriter, r *http.Request) {
@@ -1286,6 +1287,7 @@ func approvePendingHost(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/pending_hosts/reject/{id} [post]
 // @Tags        Hosts
 // @Security    oauth
+// @Param       id path string true "Pending Host ID"
 // @Success     200 {array} models.ApiNode
 // @Failure     500 {object} models.ErrorResponse
 func rejectPendingHost(w http.ResponseWriter, r *http.Request) {

controllers/network.go

@@ -531,7 +531,7 @@ func deleteNetwork(w http.ResponseWriter, r *http.Request) {
 	})
 	logger.Log(1, r.Header.Get("user"), "deleted network", network)
 	w.WriteHeader(http.StatusOK)
-	json.NewEncoder(w).Encode("success")
+	logic.ReturnSuccessResponse(w, r, "success")
 }
 
 // @Summary     Create a network

controllers/node.go

@@ -256,6 +256,7 @@ func Authorize(
 // @Router      /api/nodes/adm/{network} [get]
 // @Securitydefinitions.oauth2.application OAuth2Application
 // @Tags        Nodes
+// @Param       network path string true "Network ID"
 // @Success     200 {array} models.Node
 // @Failure     500 {object} models.ErrorResponse
 func getNetworkNodes(w http.ResponseWriter, r *http.Request) {
@@ -323,6 +324,7 @@ func getAllNodes(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/v1/nodes/{network}/status [get]
 // @Tags        Nodes
 // @Securitydefinitions.oauth2.application OAuth2Application
+// @Param       network path string true "Network ID"
 // @Success     200 {array} models.ApiNode
 // @Failure     500 {object} models.ErrorResponse
 // Not quite sure if this is necessary. Probably necessary based on front end but may want to review after iteration 1 if it's being used or not
@@ -354,6 +356,8 @@ func getNetworkNodeStatus(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/nodes/{network}/{nodeid} [get]
 // @Tags        Nodes
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       nodeid path string true "Node ID"
 // @Success     200 {object} models.NodeGet
 // @Failure     500 {object} models.ErrorResponse
 func getNode(w http.ResponseWriter, r *http.Request) {
@@ -424,6 +428,8 @@ func getNode(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/nodes/{network}/{nodeid}/creategateway [post]
 // @Tags        Nodes
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       nodeid path string true "Node ID"
 // @Success     200 {object} models.ApiNode
 // @Failure     500 {object} models.ErrorResponse
 func createEgressGateway(w http.ResponseWriter, r *http.Request) {
@@ -480,6 +486,8 @@ func createEgressGateway(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/nodes/{network}/{nodeid}/deletegateway [delete]
 // @Tags        Nodes
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       nodeid path string true "Node ID"
 // @Success     200 {object} models.ApiNode
 // @Failure     500 {object} models.ErrorResponse
 func deleteEgressGateway(w http.ResponseWriter, r *http.Request) {
@@ -525,6 +533,8 @@ func deleteEgressGateway(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/nodes/{network}/{nodeid} [put]
 // @Tags        Nodes
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       nodeid path string true "Node ID"
 // @Success     200 {object} models.ApiNode
 // @Failure     500 {object} models.ErrorResponse
 func updateNode(w http.ResponseWriter, r *http.Request) {
@@ -666,6 +676,8 @@ func updateNode(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/nodes/{network}/{nodeid} [delete]
 // @Tags        Nodes
 // @Security    oauth2
+// @Param       network path string true "Network ID"
+// @Param       nodeid path string true "Node ID"
 // @Success     200 {string} string "Node deleted."
 // @Failure     500 {object} models.ErrorResponse
 func deleteNode(w http.ResponseWriter, r *http.Request) {

controllers/server.go

@@ -5,15 +5,16 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"github.com/gravitl/netmaker/db"
-	"github.com/gravitl/netmaker/schema"
-	"github.com/google/go-cmp/cmp"
 	"net/http"
 	"os"
 	"strings"
 	"syscall"
 	"time"
 
+	"github.com/google/go-cmp/cmp"
+	"github.com/gravitl/netmaker/db"
+	"github.com/gravitl/netmaker/schema"
+
 	"github.com/gorilla/mux"
 	"golang.org/x/exp/slog"
 
@@ -139,8 +140,8 @@ func getUsage(w http.ResponseWriter, _ *http.Request) {
 // @Router      /api/server/status [get]
 // @Tags        Server
 // @Security    oauth2
+// @Success     200 {object} object "Server status"
 func getStatus(w http.ResponseWriter, r *http.Request) {
-	// @Success     200 {object} status
 	type status struct {
 		DB               bool      `json:"db_connected"`
 		Broker           bool      `json:"broker_connected"`
@@ -247,7 +248,7 @@ func getConfig(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/server/settings [get]
 // @Tags        Server
 // @Security    oauth2
-// @Success     200 {object} config.ServerSettings
+// @Success     200 {object} models.ServerSettings
 func getSettings(w http.ResponseWriter, r *http.Request) {
 	scfg := logic.GetServerSettings()
 	if scfg.ClientSecret != "" {
@@ -261,7 +262,7 @@ func getSettings(w http.ResponseWriter, r *http.Request) {
 // @Router      /api/server/settings [put]
 // @Tags        Server
 // @Security    oauth2
-// @Success     200 {object} config.ServerSettings
+// @Success     200 {object} models.ServerSettings
 func updateSettings(w http.ResponseWriter, r *http.Request) {
 	var req models.ServerSettings
 	force := r.URL.Query().Get("force")
@@ -425,7 +426,7 @@ func identifySettingsUpdateAction(old, new models.ServerSettings) models.Action
 // @Router      /api/server/feature_flags [get]
 // @Tags        Server
 // @Security    oauth2
-// @Success     200 {object} config.ServerSettings
+// @Success     200 {object} models.ServerSettings
 func getFeatureFlags(w http.ResponseWriter, r *http.Request) {
 	logic.ReturnSuccessResponseWithJson(w, r, logic.GetFeatureFlags(), "")
 }

controllers/user.go

@@ -62,7 +62,7 @@ func userHandlers(r *mux.Router) {
 }
 
 // @Summary     Authenticate a user to retrieve an authorization token
-// @Router      /api/v1/users/{username}/access_token [post]
+// @Router      /api/v1/users/access_token [post]
 // @Tags        Auth
 // @Accept      json
 // @Param       body body models.UserAuthParams true "Authentication parameters"
@@ -157,11 +157,11 @@ func createUserAccessToken(w http.ResponseWriter, r *http.Request) {
 	}, "api access token has generated for user "+req.UserName)
 }
 
-// @Summary     Authenticate a user to retrieve an authorization token
-// @Router      /api/v1/users/{username}/access_token [post]
+// @Summary     Get user access tokens
+// @Router      /api/v1/users/access_token [get]
 // @Tags        Auth
 // @Accept      json
-// @Param       body body models.UserAuthParams true "Authentication parameters"
+// @Param       username query string true "Username"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -175,11 +175,11 @@ func getUserAccessTokens(w http.ResponseWriter, r *http.Request) {
 	logic.ReturnSuccessResponseWithJson(w, r, (&schema.UserAccessToken{UserName: username}).ListByUser(r.Context()), "fetched api access tokens for user "+username)
 }
 
-// @Summary     Authenticate a user to retrieve an authorization token
-// @Router      /api/v1/users/{username}/access_token [post]
+// @Summary     Delete user access tokens
+// @Router      /api/v1/users/access_token [delete]
 // @Tags        Auth
 // @Accept      json
-// @Param       body body models.UserAuthParams true "Authentication parameters"
+// @Param       id query string true "Token ID"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse
 // @Failure     401 {object} models.ErrorResponse
@@ -453,6 +453,7 @@ func authenticateUser(response http.ResponseWriter, request *http.Request) {
 // @Router      /api/users/{username}/validate-identity [post]
 // @Tags        Auth
 // @Accept      json
+// @Param       username path string true "Username"
 // @Param       body body models.UserIdentityValidationRequest true "User Identity Validation Request"
 // @Success     200 {object} models.SuccessResponse
 // @Failure     400 {object} models.ErrorResponse