open api spec file (#2595)

* remove usergroup

* superadmin

* superadmin creation

* generate openapi spec file

* statticcheck

* review comments

auth/auth.go

@@ -136,6 +136,8 @@ func HandleAuthCallback(w http.ResponseWriter, r *http.Request) {
 //
 //			Security:
 //	  		oauth
+//			Responses:
+//			200:  okResponse
 func HandleAuthLogin(w http.ResponseWriter, r *http.Request) {
 	if auth_provider == nil {
 		handleOauthNotConfigured(w)

controllers/dns.go

@@ -33,6 +33,8 @@ func dnsHandlers(r *mux.Router) {
 //
 //			Security:
 //	  		oauth
+//			Responses:
+//			200: dnsResponse
 func getNodeDNS(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
@@ -264,8 +266,8 @@ func GetDNSEntry(domain string, network string) (models.DNSEntry, error) {
 //	  		oauth
 //
 //			Responses:
-//				200: dnsStringJSONResponse
-//				*: dnsStringJSONResponse
+//			200: dnsResponse
+//				*: dnsResponse
 func pushDNS(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")

controllers/docs.go

@@ -11,7 +11,7 @@
 //	Schemes: https
 //	BasePath: /
 //	Version: 0.21.1
-//	Host: netmaker.io
+//	Host: api.demo.netmaker.io
 //
 //	Consumes:
 //	- application/json
@@ -26,15 +26,37 @@
 package controller
 
 import (
-	serverconfigpkg "github.com/gravitl/netmaker/config"
+	"os"
+
+	"github.com/gravitl/netmaker/config"
 	"github.com/gravitl/netmaker/logic/acls"
 	"github.com/gravitl/netmaker/models"
 )
 
 var _ = useUnused() // "use" the function to prevent "unused function" errors
 
+// swagger:parameters getFile
+type filenameToGet struct {
+	// Filename
+	// in: path
+	// required: true
+	Filename string `json:"filename"`
+}
+
+// swagger:response hasAdmin
+type hasAdmin struct {
+	// in: body
+	Admin bool
+}
+
+// swagger:response apiHostResponse
+type apiHostResponse struct {
+	// in: body
+	Host models.ApiHost
+}
+
 // swagger:parameters getNodeDNS getCustomDNS getDNS
-type dnsPathParams struct {
+type dnsNetworkPathParam struct {
 	// Network
 	// in: path
 	Network string `json:"network"`
@@ -45,7 +67,6 @@ type dnsParams struct {
 	// Network
 	// in: path
 	Network string `json:"network"`
-
 	// DNS Entry
 	// in: body
 	Body []models.DNSEntry `json:"body"`
@@ -76,6 +97,18 @@ type stringJSONResponse struct {
 	Response string `json:"response"`
 }
 
+//swagger:response EnrollmentKey
+type EnrollmentKey struct {
+	// in: body
+	EnrollmentKey models.EnrollmentKey
+}
+
+//swagger:response EnrollmentKeys
+type EnrollmentKeys struct {
+	// in: body
+	EnrollmentKeys []models.EnrollmentKey
+}
+
 // swagger:parameters getAllExtClients
 type getAllClientsRequest struct {
 	// Networks
@@ -97,6 +130,12 @@ type extClientResponse struct {
 	ExtClient models.ExtClient `json:"ext_client"`
 }
 
+// swagger:response fileResponse
+type fileResponse struct {
+	// in: body
+	File os.File
+}
+
 // swagger:response successResponse
 type successResponse struct {
 	// Success Response
@@ -104,12 +143,24 @@ type successResponse struct {
 	SuccessResponse models.SuccessResponse `json:"success_response"`
 }
 
+// swagger:parameters getExtClientConf
+type extClientConfParams struct {
+	// Client ID
+	// in: path
+	ClientID string `json:"clientid"`
+	// Network
+	// in: path
+	Network string `json:"network"`
+	// Type
+	// in: path
+	Type string `json:"type"`
+}
+
 // swagger:parameters getExtClient getExtClientConf updateExtClient deleteExtClient
 type extClientPathParams struct {
 	// Client ID
 	// in: path
 	ClientID string `json:"clientid"`
-
 	// Network
 	// in: path
 	Network string `json:"network"`
@@ -137,20 +188,17 @@ type createExtClientPathParams struct {
 
 	// Node ID
 	// in: path
-	NodeID string `json:"node"`
+	NodeID string `json:"nodeid"`
 
 	// Custom ExtClient
 	// in: body
 	CustomExtClient models.CustomExtClient `json:"custom_ext_client"`
 }
 
-// swagger:parameters getNode updateNode deleteNode createRelay deleteRelay createEgressGateway deleteEgressGateway createIngressGateway deleteIngressGateway uncordonNode
+// swagger:parameters getNode updateNode deleteNode createRelay deleteRelay createEgressGateway deleteEgressGateway createIngressGateway deleteIngressGateway ingressGatewayUsers
 type networkNodePathParams struct {
-	// Network
 	// in: path
 	Network string `json:"network"`
-
-	// Node ID
 	// in: path
 	NodeID string `json:"nodeid"`
 }
@@ -161,11 +209,11 @@ type byteArrayResponse struct {
 	ByteArray []byte `json:"byte_array"`
 }
 
-// swagger:parameters getNetworks
-type headerNetworks struct {
-	// name: networks
-	// in: header
-	Networks []string `json:"networks"`
+// swagger:parameters getNetwork deleteNetwork updateNetwork getNetworkACL updateNetworkACL
+type NetworkParam struct {
+	// name: network name
+	// in:  path
+	Networkname string `json:"networkname"`
 }
 
 // swagger:response getNetworksSliceResponse
@@ -175,6 +223,13 @@ type getNetworksSliceResponse struct {
 	Networks []models.Network `json:"networks"`
 }
 
+// swagger:response hostPull
+type hostPull struct {
+	// hostPull
+	// in: body
+	HostPull models.HostPull
+}
+
 // swagger:parameters createNetwork updateNetwork
 type networkBodyParam struct {
 	// Network
@@ -182,18 +237,11 @@ type networkBodyParam struct {
 	Network models.Network `json:"network"`
 }
 
-// swagger:parameters updateNetwork getNetwork updateNetwork updateNetworkNodeLimit deleteNetwork keyUpdate createAccessKey getAccessKeys deleteAccessKey updateNetworkACL getNetworkACL
+// swagger:parameters updateNetworkNodeLimit keyUpdate createAccessKey getAccessKeys getNetworkNodes
 type networkPathParam struct {
-	// Network Name
-	// in: path
-	NetworkName string `json:"networkname"`
-}
-
-// swagger:parameters deleteAccessKey
-type networkAccessKeyNamePathParam struct {
-	// Access Key Name
+	// Network
 	// in: path
-	AccessKeyName string `json:"access_key_name"`
+	Network string `json:"network"`
 }
 
 // swagger:response networkBodyResponse
@@ -238,6 +286,15 @@ type nodeBodyParam struct {
 	Node models.LegacyNode `json:"node"`
 }
 
+//swagger:response okResponse
+type okRespone struct{}
+
+// swagger:response RegisterResponse
+type RegisterResponse struct {
+	// in: body
+	RegisterResponse models.RegisterResponse
+}
+
 // swagger:parameters createRelay
 type relayRequestBodyParam struct {
 	// Relay Request
@@ -252,53 +309,68 @@ type egressGatewayBodyParam struct {
 	EgressGatewayRequest models.EgressGatewayRequest `json:"egress_gateway_request"`
 }
 
+// swagger:parameters attachUserToRemoteAccessGateway removeUserFromRemoteAccessGW getUserRemoteAccessGws
+type RemoteAccessGatewayUser struct {
+	// in: path
+	Username string `json:"username"`
+}
+
 // swagger:parameters authenticate
 type authParamBodyParam struct {
+	// network
+	// in: path
+	Network string `json:"network"`
 	// AuthParams
 	// in: body
 	AuthParams models.AuthParams `json:"auth_params"`
 }
 
-// swagger:response serverConfigResponse
-type serverConfigResponse struct {
-	// Server Config
+// swagger:response signal
+type signal struct {
 	// in: body
-	ServerConfig serverconfigpkg.ServerConfig `json:"server_config"`
+	Signal models.Signal
 }
 
-// swagger:response nodeGetResponse
-type nodeGetResponse struct {
-	// Node Get
-	// in: body
-	NodeGet models.NodeGet `json:"node_get"`
+// swagger:parameters synchost deleteHost updateHost signalPeer updateKeys
+type HostID struct {
+	// HostID
+	// in: path
+	HostID string `json:"hostid"`
 }
 
-// swagger:response nodeLastModifiedResponse
-type nodeLastModifiedResponse struct {
-	// Node Last Modified
-	// in: body
-	NodesLastModified int64 `json:"nodes_last_modified"`
+// swagger:parameters addHostToNetwork deleteHostFromNetwork
+type HostFromNetworkParams struct {
+	// hostid to add or delete from network
+	// in: path
+	HostID string `json:"hostid"`
+	// network
+	// in: path
+	Network string `json:"network"`
 }
 
-// swagger:parameters register
-//type registerRequestBodyParam struct {
-//	// Register Request
-//	// in: body
-//	RegisterRequest config.RegisterRequest `json:"register_request"`
-//}
-//
-//// swagger:response registerResponse
-//type registerResponse struct {
-//	// Register Response
-//	// in: body
-//	RegisterResponse config.RegisterResponse `json:"register_response"`
-//}
+// swagger:parameters deleteEnrollmentKey
+type DeleteEnrollmentKeyParam struct {
+	// in: path
+	KeyID string `json:"keyid"`
+}
 
-// swagger:response boolResponse
-type boolResponse struct {
-	// Boolean Response
+// swagger:parameters handleHostRegister
+type RegisterParams struct {
+	// in: path
+	Token string `json:"token"`
+	// in: body
+	Host models.Host `json:"host"`
+}
+
+// swagger:response serverConfigResponse
+type serverConfigResponse struct {
+	// Server Config
 	// in: body
-	BoolResponse bool `json:"bool_response"`
+	// example
+	//{
+	//"mqusername": "xxxxxxx"
+	//}
+	ServerConfig config.ServerConfig `json:"server_config"`
 }
 
 // swagger:parameters createAdmin updateUser updateUserNetworks createUser
@@ -331,7 +403,6 @@ type usernamePathParam struct {
 
 // prevent issues with integration tests for types just used by Swagger docs.
 func useUnused() bool {
-	_ = dnsPathParams{}
 	_ = dnsParams{}
 	_ = dnsResponse{}
 	_ = dnsDeletePathParams{}
@@ -346,11 +417,9 @@ func useUnused() bool {
 	_ = createExtClientPathParams{}
 	_ = networkNodePathParams{}
 	_ = byteArrayResponse{}
-	_ = headerNetworks{}
 	_ = getNetworksSliceResponse{}
 	_ = networkBodyParam{}
 	_ = networkPathParam{}
-	_ = networkAccessKeyNamePathParam{}
 	_ = networkBodyResponse{}
 	_ = aclContainerBodyParam{}
 	_ = aclContainerResponse{}
@@ -361,14 +430,18 @@ func useUnused() bool {
 	_ = egressGatewayBodyParam{}
 	_ = authParamBodyParam{}
 	_ = serverConfigResponse{}
-	_ = nodeGetResponse{}
-	_ = nodeLastModifiedResponse{}
-	//	_ = registerRequestBodyParam{}
-	//	_ = registerResponse{}
-	_ = boolResponse{}
 	_ = userBodyParam{}
 	_ = userBodyResponse{}
 	_ = userAuthBodyParam{}
 	_ = usernamePathParam{}
+	_ = hasAdmin{}
+	_ = apiHostResponse{}
+	_ = fileResponse{}
+	_ = extClientConfParams{}
+	_ = hostPull{}
+	_ = okRespone{}
+	_ = signal{}
+	_ = filenameToGet{}
+	_ = dnsNetworkPathParam{}
 	return false
 }

controllers/enrollmentkeys.go

@@ -33,7 +33,7 @@ func enrollmentKeyHandlers(r *mux.Router) {
 //	  		oauth
 //
 //			Responses:
-//				200: getEnrollmentKeysSlice
+//				200: EnrollmentKeys
 func getEnrollmentKeys(w http.ResponseWriter, r *http.Request) {
 	keys, err := logic.GetAllEnrollmentKeys()
 	if err != nil {
@@ -58,7 +58,7 @@ func getEnrollmentKeys(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(ret)
 }
 
-// swagger:route DELETE /api/v1/enrollment-keys/{keyID} enrollmentKeys deleteEnrollmentKey
+// swagger:route DELETE /api/v1/enrollment-keys/{keyid} enrollmentKeys deleteEnrollmentKey
 //
 // Deletes an EnrollmentKey from Netmaker server.
 //
@@ -68,7 +68,7 @@ func getEnrollmentKeys(w http.ResponseWriter, r *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: deleteEnrollmentKeyResponse
+//				200: okResponse
 func deleteEnrollmentKey(w http.ResponseWriter, r *http.Request) {
 	var params = mux.Vars(r)
 	keyID := params["keyID"]
@@ -92,7 +92,7 @@ func deleteEnrollmentKey(w http.ResponseWriter, r *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: createEnrollmentKeyResponse
+//				200: EnrollmentKey
 func createEnrollmentKey(w http.ResponseWriter, r *http.Request) {
 
 	var enrollmentKeyBody models.APIEnrollmentKey
@@ -136,7 +136,7 @@ func createEnrollmentKey(w http.ResponseWriter, r *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: handleHostRegisterResponse
+//				200: RegisterResponse
 func handleHostRegister(w http.ResponseWriter, r *http.Request) {
 	var params = mux.Vars(r)
 	token := params["token"]

controllers/ext_client.go

@@ -303,6 +303,8 @@ Endpoint = %s
 //
 //			Security:
 //	  		oauth
+//			Responses:
+//			200:  okResponse
 func createExtClient(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 

controllers/files.go

@@ -7,7 +7,7 @@ import (
 )
 
 func fileHandlers(r *mux.Router) {
-	// swagger:route GET /meshclient/files/{filename} meshclient fileServer
+	// swagger:route GET /meshclient/files/{filename} meshclient getFile
 	//
 	// Retrieve a file from the file server.
 	//
@@ -15,5 +15,7 @@ func fileHandlers(r *mux.Router) {
 	//
 	// 		Security:
 	//   		oauth
+	//		Responses:
+	//		200: fileResponse
 	r.PathPrefix("/meshclient/files").Handler(http.StripPrefix("/meshclient/files", http.FileServer(http.Dir("./meshclient/files"))))
 }

controllers/hosts.go

@@ -58,7 +58,7 @@ func upgradeHost(w http.ResponseWriter, r *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: getHostsSliceResponse
+//				200: apiHostResponse
 func getHosts(w http.ResponseWriter, r *http.Request) {
 	currentHosts, err := logic.GetAllHosts()
 	if err != nil {
@@ -73,7 +73,7 @@ func getHosts(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(apiHosts)
 }
 
-// swagger:route GET /api/v1/host pull pullHost
+// swagger:route GET /api/v1/host hosts pullHost
 //
 // Used by clients for "pull" command
 //
@@ -83,7 +83,7 @@ func getHosts(w http.ResponseWriter, r *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: pull
+//				200: hostPull
 func pull(w http.ResponseWriter, r *http.Request) {
 
 	hostID := r.Header.Get(hostIDHeader) // return JSON/API formatted keys
@@ -145,7 +145,7 @@ func pull(w http.ResponseWriter, r *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: updateHostResponse
+//				200: apiHostResponse
 func updateHost(w http.ResponseWriter, r *http.Request) {
 	var newHostData models.ApiHost
 	err := json.NewDecoder(r.Body).Decode(&newHostData)
@@ -213,7 +213,7 @@ func updateHost(w http.ResponseWriter, r *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: deleteHostResponse
+//				200: apiHostResponse
 func deleteHost(w http.ResponseWriter, r *http.Request) {
 	var params = mux.Vars(r)
 	hostid := params["hostid"]
@@ -252,9 +252,8 @@ func deleteHost(w http.ResponseWriter, r *http.Request) {
 //
 //			Security:
 //	  		oauth
-//
 //			Responses:
-//				200: addHostToNetworkResponse
+//				200: okResponse
 func addHostToNetwork(w http.ResponseWriter, r *http.Request) {
 
 	var params = mux.Vars(r)
@@ -301,7 +300,7 @@ func addHostToNetwork(w http.ResponseWriter, r *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: deleteHostFromNetworkResponse
+//				200: okResponse
 func deleteHostFromNetwork(w http.ResponseWriter, r *http.Request) {
 
 	var params = mux.Vars(r)
@@ -378,7 +377,7 @@ func deleteHostFromNetwork(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusOK)
 }
 
-// swagger:route POST /api/hosts/adm/authenticate hosts authenticateHost
+// swagger:route POST /api/hosts/adm/authenticate authenticate authenticateHost
 //
 // Host based authentication for making further API calls.
 //
@@ -471,7 +470,7 @@ func authenticateHost(response http.ResponseWriter, request *http.Request) {
 	response.Write(successJSONResponse)
 }
 
-// swagger:route POST /api/hosts/{hostid}/signalpeer signalPeer
+// swagger:route POST /api/hosts/{hostid}/signalpeer hosts signalPeer
 //
 // send signal to peer.
 //
@@ -537,7 +536,7 @@ func signalPeer(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(signal)
 }
 
-// swagger:route POST /api/hosts/keys host updateAllKeys
+// swagger:route POST /api/hosts/keys hosts updateAllKeys
 //
 // Update keys for a network.
 //
@@ -575,7 +574,7 @@ func updateAllKeys(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusOK)
 }
 
-// swagger:route POST /api/hosts/{hostid}keys host updateKeys
+// swagger:route POST /api/hosts/{hostid}keys hosts updateKeys
 //
 // Update keys for a network.
 //
@@ -614,7 +613,7 @@ func updateKeys(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusOK)
 }
 
-// swagger:route POST /api/hosts/{hostId}/sync host syncHost
+// swagger:route POST /api/hosts/{hostid}/sync hosts synchost
 //
 // Requests a host to pull.
 //

controllers/legacy.go

@@ -22,7 +22,7 @@ func legacyHandlers(r *mux.Router) {
 //	  		oauth
 //
 //			Responses:
-//				200: wipeLegacyNodesResponse
+//				200: successResponse
 func wipeLegacyNodes(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")

controllers/migrate.go

@@ -19,7 +19,7 @@ import (
 	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
 )
 
-// swagger:route PUT /api/v1/nodes/migrate nodes migrateNode
+// swagger:route PUT /api/v1/nodes/migrate nodes migrateData
 //
 // Used to migrate a legacy node.
 //
@@ -29,7 +29,7 @@ import (
 //	  		oauth
 //
 //			Responses:
-//				200: nodeJoinResponse
+//				200: hostPull
 func migrate(w http.ResponseWriter, r *http.Request) {
 	data := models.MigrationData{}
 	host := models.Host{}

controllers/network.go

@@ -180,7 +180,7 @@ func getNetworkACL(w http.ResponseWriter, r *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: stringJSONResponse
+//				200: successResponse
 func deleteNetwork(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")
@@ -278,7 +278,7 @@ func createNetwork(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(network)
 }
 
-// swagger:route PUT /api/networks networks updateNetwork
+// swagger:route PUT /api/networks/{networkname} networks updateNetwork
 //
 // Update pro settings for a network.
 //

controllers/node.go

@@ -34,7 +34,7 @@ func nodeHandlers(r *mux.Router) {
 	r.HandleFunc("/api/v1/nodes/migrate", migrate).Methods(http.MethodPost)
 }
 
-// swagger:route POST /api/nodes/adm/{network}/authenticate nodes authenticate
+// swagger:route POST /api/nodes/adm/{network}/authenticate authenticate authenticate
 //
 // Authenticate to make further API calls related to a network.
 //

controllers/user.go

@@ -37,9 +37,9 @@ func userHandlers(r *mux.Router) {
 	r.HandleFunc("/api/oauth/register/{regKey}", auth.RegisterHostSSO).Methods(http.MethodGet)
 }
 
-// swagger:route POST /api/users/adm/authenticate user authenticateUser
+// swagger:route POST /api/users/adm/authenticate authenticate authenticateUser
 //
-// Node authenticates using its password and retrieves a JWT for authorization.
+// User authenticates using its password and retrieves a JWT for authorization.
 //
 //			Schemes: https
 //
@@ -145,7 +145,7 @@ func authenticateUser(response http.ResponseWriter, request *http.Request) {
 //	  		oauth
 //
 //			Responses:
-//				200: successResponse
+//				200: hasAdmin
 func hasSuperAdmin(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")

pro/controllers/users.go

@@ -78,7 +78,7 @@ func attachUserToRemoteAccessGw(w http.ResponseWriter, r *http.Request) {
 
 // swagger:route DELETE /api/users/{username}/remote_access_gw user removeUserFromRemoteAccessGW
 //
-// Attach User to a remote access gateway.
+// Delete User from a remote access gateway.
 //
 //			Schemes: https
 //