Added swagger for API docs.

auth/auth.go

@@ -82,6 +82,7 @@ func InitializeAuthProvider() string {
 	return authInfo[0]
 }
 
+// Not included in API reference as part of the OAuth process itself.
 // HandleAuthCallback - handles oauth callback
 func HandleAuthCallback(w http.ResponseWriter, r *http.Request) {
 	if auth_provider == nil {
@@ -96,7 +97,14 @@ func HandleAuthCallback(w http.ResponseWriter, r *http.Request) {
 	functions[handle_callback].(func(http.ResponseWriter, *http.Request))(w, r)
 }
 
-// HandleAuthLogin - handles oauth login
+// swagger:route GET /api/oauth/login nodes HandleAuthLogin
+//
+// Handles OAuth login
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func HandleAuthLogin(w http.ResponseWriter, r *http.Request) {
 	if auth_provider == nil {
 		var referer = r.Header.Get("referer")

controllers/dns.go

@@ -25,7 +25,14 @@ func dnsHandlers(r *mux.Router) {
 	r.HandleFunc("/api/dns/{network}/{domain}", securityCheck(false, http.HandlerFunc(deleteDNS))).Methods("DELETE")
 }
 
-//Gets node DNS entries associated with a network
+// swagger:route GET /api/dns/adm/{network}/nodes dns getNodeDNS
+//
+// Gets node DNS entries associated with a network
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getNodeDNS(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
@@ -44,7 +51,14 @@ func getNodeDNS(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(dns)
 }
 
-//Gets all DNS entries.
+// swagger:route GET /api/dns dns getAllDNS
+//
+// Gets all DNS entries
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getAllDNS(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	dns, err := logic.GetAllDNS()
@@ -57,7 +71,14 @@ func getAllDNS(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(dns)
 }
 
-//Gets custom DNS entries associated with a network
+// swagger:route GET /api/dns/adm/{network}/custom dns getCustomDNS
+//
+// Gets custom DNS entries associated with a network
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getCustomDNS(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
@@ -76,7 +97,14 @@ func getCustomDNS(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(dns)
 }
 
+// swagger:route GET /api/dns/adm/{network} dns getDNS
+//
 // Gets all DNS entries associated with the network
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getDNS(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
@@ -95,6 +123,14 @@ func getDNS(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(dns)
 }
 
+// swagger:route POST /api/dns/{network} dns createDNS
+//
+// Create a DNS entry
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func createDNS(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
@@ -146,6 +182,14 @@ func createDNS(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(entry)
 }
 
+// swagger:route DELETE /api/dns/{network}/{domain} dns deleteDNS
+//
+// Delete a DNS entry
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func deleteDNS(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")
@@ -202,6 +246,14 @@ func GetDNSEntry(domain string, network string) (models.DNSEntry, error) {
 	return entry, err
 }
 
+// swagger:route POST /api/dns/adm/pushdns dns pushDNS
+//
+// Push DNS entries to nameserver
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func pushDNS(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")

controllers/docs.go

@@ -1,7 +1,13 @@
-// TODO update to follow actual info..  just set up enough to try out Swagger
+//Package classification Controller.
-// Package classification Controller.
 //
-// Documentation of the Netmaker API.
+// API Usage
+//
+// Most actions that can be performed via API can be performed via UI. We recommend managing your networks using the official netmaker-ui project. However, Netmaker can also be run without the UI, and all functions can be achieved via API calls. If your use case requires using Netmaker without the UI or you need to do some troubleshooting/advanced configuration, using the API directly may help.
+//
+//
+// Authentication
+//
+// API calls must be authenticated via a header of the format -H “Authorization: Bearer <YOUR_SECRET_KEY>” There are two methods to obtain YOUR_SECRET_KEY: 1. Using the masterkey. By default, this value is “secret key,” but you should change this on your instance and keep it secure. This value can be set via env var at startup or in a config file (config/environments/< env >.yaml). See the [general usage](./USAGE.md) documentation for more details. 2. Using a JWT received for a node. This can be retrieved by calling the /api/nodes/<network>/authenticate endpoint, as documented below.
 //
 //     Schemes: https
 //     BasePath: /
@@ -17,9 +23,5 @@
 //     Security:
 //     - oauth
 //
-//    SecurityDefinitions:
-//    basic:
-//      type: basic
-//
 // swagger:meta
 package controller

controllers/ext_client.go

@@ -36,7 +36,15 @@ func checkIngressExists(nodeID string) bool {
 	return node.IsIngressGateway == "yes"
 }
 
-//Gets all extclients associated with network, including pending extclients
+// swagger:route GET /api/extclients/{network} ext_client getNetworkExtClients
+//
+// Get all extclients associated with network
+// Gets all extclients associated with network, including pending extclients
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getNetworkExtClients(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
@@ -57,8 +65,18 @@ func getNetworkExtClients(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(extclients)
 }
 
-//A separate function to get all extclients, not just extclients for a particular network.
+// swagger:route GET /api/extclients ext_client getAllExtClients
-//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
+//
+// A separate function to get all extclients, not just extclients for a particular network.
+//
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
+// 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
 func getAllExtClients(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
@@ -95,7 +113,15 @@ func getAllExtClients(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(clients)
 }
 
-//Get an individual extclient. Nothin fancy here folks.
+// swagger:route GET /api/extclients ext_client getExtClient
+//
+// Get an individual extclient.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
 func getExtClient(w http.ResponseWriter, r *http.Request) {
 	// set header.
 	w.Header().Set("Content-Type", "application/json")
@@ -116,7 +142,15 @@ func getExtClient(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(client)
 }
 
-//Get an individual extclient. Nothin fancy here folks.
+// swagger:route GET /api/extclients/{network}/{clientid}/{type} ext_client getExtClientConf
+//
+// Get an individual extclient.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
 func getExtClientConf(w http.ResponseWriter, r *http.Request) {
 	// set header.
 	w.Header().Set("Content-Type", "application/json")
@@ -240,10 +274,15 @@ Endpoint = %s
 	json.NewEncoder(w).Encode(client)
 }
 
-/**
+// swagger:route POST /api/extclients/{network}/{nodeid} ext_client createExtClient
- * To create a extclient
+//
- * Must have valid key and be unique
+// Create an individual extclient.  Must have valid key and be unique.
- */
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
 func createExtClient(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
@@ -292,6 +331,15 @@ func createExtClient(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+// swagger:route PUT /api/extclients/{network}/{clientid} ext_client updateExtClient
+//
+// Update an individual extclient.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
 func updateExtClient(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
@@ -351,8 +399,15 @@ func updateExtClient(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(newclient)
 }
 
-//Delete a extclient
+// swagger:route DELETE /api/extclients/{network}/{clientid} ext_client deleteExtClient
-//Pretty straightforward
+//
+// Delete an individual extclient.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
 func deleteExtClient(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")

controllers/ipservice.go

@@ -14,6 +14,15 @@ func ipHandlers(r *mux.Router) {
 	r.HandleFunc("/api/getip", http.HandlerFunc(getPublicIP)).Methods("GET")
 }
 
+// swagger:route GET /api/getip ipservice getPublicIP
+//
+// Get the current public IP address
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
 func getPublicIP(w http.ResponseWriter, r *http.Request) {
 	r.Header.Set("Connection", "close")
 	ip, err := parseIP(r)

controllers/network.go

@@ -43,8 +43,6 @@ func networkHandlers(r *mux.Router) {
 //
 // Lists all networks
 //
-// simple get all networks function
-//
 //		Schemes: https
 //
 // 		Security:
@@ -89,7 +87,14 @@ func getNetworks(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(allnetworks)
 }
 
-// Simple get network function
+// swagger:route GET /api/networks networks getNetwork
+//
+// Get a network
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getNetwork(w http.ResponseWriter, r *http.Request) {
 	// set header.
 	w.Header().Set("Content-Type", "application/json")
@@ -110,6 +115,14 @@ func getNetwork(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(network)
 }
 
+// swagger:route POST /api/networks/{networkname}/keyupdate networks keyUpdate
+//
+// Update keys for a network.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func keyUpdate(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -139,7 +152,14 @@ func keyUpdate(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+// swagger:route PUT /api/networks/{networkname} networks updateNetwork
+//
 // Update a network
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func updateNetwork(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -234,6 +254,14 @@ func updateNetwork(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(newNetwork)
 }
 
+// swagger:route PUT /api/networks/{networkname}/nodelimit networks updateNetworkNodeLimit
+//
+// Update a network's node limit
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func updateNetworkNodeLimit(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -273,6 +301,14 @@ func updateNetworkNodeLimit(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(network)
 }
 
+// swagger:route PUT /api/networks/{networkname}/acls networks updateNetworkACL
+//
+// Update a network ACL (Access Control List).
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func updateNetworkACL(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -320,6 +356,14 @@ func updateNetworkACL(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(newNetACL)
 }
 
+// swagger:route GET /api/networks/{networkname}/acls networks getNetworkACL
+//
+// Get a network ACL (Access Control List).
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getNetworkACL(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -337,8 +381,14 @@ func getNetworkACL(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(networkACL)
 }
 
-// Delete a network
+// swagger:route DELETE /api/networks/{networkname} networks deleteNetwork
-// Will stop you if  there's any nodes associated
+//
+// Delete a network.  Will not delete if there are any nodes that belong to the network.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func deleteNetwork(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")
@@ -361,6 +411,14 @@ func deleteNetwork(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode("success")
 }
 
+// swagger:route POST /api/networks networks createNetwork
+//
+// Create a network
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func createNetwork(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
@@ -411,6 +469,15 @@ func createNetwork(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(network)
 }
 
+// swagger:route POST /api/networks/{networkname}/keys networks createAccessKey
+//
+// Create a network access key.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
 // BEGIN KEY MANAGEMENT SECTION
 func createAccessKey(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
@@ -444,7 +511,14 @@ func createAccessKey(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(key)
 }
 
-// pretty simple get
+// swagger:route GET /api/networks/{networkname}/keys networks getAccessKeys
+//
+// Get network access keys for a network.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getAccessKeys(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -464,6 +538,15 @@ func getAccessKeys(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(keys)
 }
 
+// swagger:route GET /api/networks/{networkname}/keys/{name} networks deleteAccessKey
+//
+// Delete a network access key.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
 // delete key. Has to do a little funky logic since it's not a collection item
 func deleteAccessKey(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")

controllers/node.go

@@ -36,6 +36,14 @@ func nodeHandlers(r *mux.Router) {
 	r.HandleFunc("/api/nodes/adm/{network}/authenticate", authenticate).Methods("POST")
 }
 
+// swagger:route POST /api/nodes/adm/{network}/authenticate nodes authenticate
+//
+// Authenticate to make further API calls related to a network.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func authenticate(response http.ResponseWriter, request *http.Request) {
 
 	var authRequest models.AuthParams
@@ -302,7 +310,14 @@ func authorize(nodesAllowed, networkCheck bool, authNetwork string, next http.Ha
 	}
 }
 
-// Gets all nodes associated with network, including pending nodes
+// swagger:route GET /api/nodes/{network} nodes getNetworkNodes
+//
+// Gets all nodes associated with network including pending nodes
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getNetworkNodes(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
@@ -325,7 +340,14 @@ func getNetworkNodes(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(nodes)
 }
 
-// A separate function to get all nodes, not just nodes for a particular network.
+// swagger:route GET /api/nodes nodes getAllNodes
+//
+// Get all nodes across all networks.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 // 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
 func getAllNodes(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
@@ -372,7 +394,14 @@ func getUsersNodes(user models.User) ([]models.Node, error) {
 	return nodes, err
 }
 
-// Get an individual node. Nothin fancy here folks.
+// swagger:route GET /api/nodes/{network}/{nodeid} nodes getNode
+//
+// Get an individual node.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getNode(w http.ResponseWriter, r *http.Request) {
 	// set header.
 	w.Header().Set("Content-Type", "application/json")
@@ -406,7 +435,14 @@ func getNode(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(response)
 }
 
+// swagger:route GET /api/nodes/adm/{network}/lastmodified nodes getLastModified
+//
 // Get the time that a network of nodes was last modified.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 // TODO: This needs to be refactored
 // Potential way to do this: On UpdateNode, set a new field for "LastModified"
 // If we go with the existing way, we need to at least set network.NodesLastModified on UpdateNode
@@ -428,6 +464,14 @@ func getLastModified(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(network.NodesLastModified)
 }
 
+// swagger:route POST /api/nodes/{network} nodes createNode
+//
+// Create a node on a network.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func createNode(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
@@ -547,6 +591,14 @@ func createNode(w http.ResponseWriter, r *http.Request) {
 	runForceServerUpdate(&node, true)
 }
 
+// swagger:route POST /api/nodes/{network}/{nodeid}/approve nodes uncordonNode
+//
+// Takes a node out of pending state.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 // Takes node out of pending state
 // TODO: May want to use cordon/uncordon terminology instead of "ispending".
 func uncordonNode(w http.ResponseWriter, r *http.Request) {
@@ -569,6 +621,14 @@ func uncordonNode(w http.ResponseWriter, r *http.Request) {
 
 // == EGRESS ==
 
+// swagger:route POST /api/nodes/{network}/{nodeid}/creategateway nodes createEgressGateway
+//
+// Create an egress gateway.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func createEgressGateway(w http.ResponseWriter, r *http.Request) {
 	var gateway models.EgressGatewayRequest
 	var params = mux.Vars(r)
@@ -597,6 +657,14 @@ func createEgressGateway(w http.ResponseWriter, r *http.Request) {
 	runUpdates(&node, true)
 }
 
+// swagger:route DELETE /api/nodes/{network}/{nodeid}/deletegateway nodes deleteEgressGateway
+//
+// Delete an egress gateway.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func deleteEgressGateway(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -620,6 +688,14 @@ func deleteEgressGateway(w http.ResponseWriter, r *http.Request) {
 
 // == INGRESS ==
 
+// swagger:route POST /api/nodes/{network}/{nodeid}/createingress nodes createIngressGateway
+//
+// Create an ingress gateway.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func createIngressGateway(w http.ResponseWriter, r *http.Request) {
 	var params = mux.Vars(r)
 	w.Header().Set("Content-Type", "application/json")
@@ -641,6 +717,14 @@ func createIngressGateway(w http.ResponseWriter, r *http.Request) {
 	runUpdates(&node, true)
 }
 
+// swagger:route DELETE /api/nodes/{network}/{nodeid}/deleteingress nodes deleteIngressGateway
+//
+// Delete an ingress gateway.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func deleteIngressGateway(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -662,6 +746,14 @@ func deleteIngressGateway(w http.ResponseWriter, r *http.Request) {
 	runUpdates(&node, true)
 }
 
+// swagger:route PUT /api/nodes/{network}/{nodeid} nodes updateNode
+//
+// Update an individual node.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func updateNode(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
@@ -756,6 +848,14 @@ func updateNode(w http.ResponseWriter, r *http.Request) {
 	runUpdates(&newNode, ifaceDelta)
 }
 
+// swagger:route DELETE /api/nodes/{network}/{nodeid} nodes deleteNode
+//
+// Delete an individual node.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func deleteNode(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")

controllers/relay.go

@@ -12,6 +12,14 @@ import (
 	"github.com/gravitl/netmaker/mq"
 )
 
+// swagger:route POST /api/nodes/{network}/{nodeid}/createrelay nodes createRelay
+//
+// Create a relay.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func createRelay(w http.ResponseWriter, r *http.Request) {
 	var relay models.RelayRequest
 	var params = mux.Vars(r)
@@ -43,6 +51,14 @@ func createRelay(w http.ResponseWriter, r *http.Request) {
 	runUpdates(&node, true)
 }
 
+// swagger:route DELETE /api/nodes/{network}/{nodeid}/deleterelay nodes deleteRelay
+//
+// Remove a relay.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func deleteRelay(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)

controllers/server.go

@@ -67,6 +67,14 @@ func securityCheckServer(adminonly bool, next http.Handler) http.HandlerFunc {
 	}
 }
 
+// swagger:route DELETE /api/server/removenetwork/{network} nodes removeNetwork
+//
+// Remove a network from the server.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func removeNetwork(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")
@@ -86,6 +94,14 @@ func removeNetwork(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(fmt.Sprintf("network %s removed from server", network))
 }
 
+// swagger:route GET /api/server/getserverinfo nodes getServerInfo
+//
+// Get the server configuration.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getServerInfo(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")
@@ -96,6 +112,14 @@ func getServerInfo(w http.ResponseWriter, r *http.Request) {
 	//w.WriteHeader(http.StatusOK)
 }
 
+// swagger:route GET /api/server/getconfig nodes getConfig
+//
+// Get the server configuration.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getConfig(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")
@@ -107,7 +131,14 @@ func getConfig(w http.ResponseWriter, r *http.Request) {
 	//w.WriteHeader(http.StatusOK)
 }
 
-// register - registers a client with the server and return the CA and cert
+// swagger:route POST /api/server/register nodes register
+//
+// Registers a client with the server and return the Certificate Authority and certificate
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func register(w http.ResponseWriter, r *http.Request) {
 	logger.Log(2, "processing registration request")
 	w.Header().Set("Content-Type", "application/json")

controllers/user.go

@@ -30,7 +30,15 @@ func userHandlers(r *mux.Router) {
 	r.HandleFunc("/api/oauth/callback", auth.HandleAuthCallback).Methods("GET")
 }
 
+// swagger:route POST /api/users/adm/authenticate nodes authenticateUser
+//
 // Node authenticates using its password and retrieves a JWT for authorization.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
+//
 func authenticateUser(response http.ResponseWriter, request *http.Request) {
 
 	// Auth request consists of Mac Address and Password (from node that is authorizing
@@ -87,6 +95,14 @@ func authenticateUser(response http.ResponseWriter, request *http.Request) {
 	response.Write(successJSONResponse)
 }
 
+// swagger:route GET /api/users/adm/hasadmin nodes hasAdmin
+//
+// Checks whether the server has an admin.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func hasAdmin(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
@@ -116,7 +132,14 @@ func GetUserInternal(username string) (models.User, error) {
 	return user, err
 }
 
-// Get an individual user. Nothin fancy here folks.
+// swagger:route GET /api/users/{username} nodes getUser
+//
+// Get an individual user.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getUser(w http.ResponseWriter, r *http.Request) {
 	// set header.
 	w.Header().Set("Content-Type", "application/json")
@@ -134,7 +157,14 @@ func getUser(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(user)
 }
 
-// Get all users. Nothin fancy here folks.
+// swagger:route GET /api/users nodes getUsers
+//
+// Get all users
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func getUsers(w http.ResponseWriter, r *http.Request) {
 	// set header.
 	w.Header().Set("Content-Type", "application/json")
@@ -151,6 +181,14 @@ func getUsers(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(users)
 }
 
+// swagger:route POST /api/users/adm/createadmin nodes createAdmin
+//
+// Make a user an admin.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func createAdmin(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
@@ -176,6 +214,14 @@ func createAdmin(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(admin)
 }
 
+// swagger:route POST /api/users/{username} nodes createUser
+//
+// Create a user.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func createUser(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
@@ -198,6 +244,14 @@ func createUser(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(user)
 }
 
+// swagger:route PUT /api/users/networks/{username} nodes updateUserNetworks
+//
+// Updates the networks of the given user
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func updateUserNetworks(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -231,6 +285,14 @@ func updateUserNetworks(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(user)
 }
 
+// swagger:route PUT /api/users/{username} nodes updateUser
+//
+// Update a user.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func updateUser(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -271,6 +333,14 @@ func updateUser(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(user)
 }
 
+// swagger:route PUT /api/users/{username}/adm nodes updateUserAdm
+//
+// Updates the given admin user's info (as long as the user is an admin)
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func updateUserAdm(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	var params = mux.Vars(r)
@@ -312,6 +382,14 @@ func updateUserAdm(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(user)
 }
 
+// swagger:route DELETE /api/users/{username} nodes deleteUser
+//
+// Delete a user.
+//
+//		Schemes: https
+//
+// 		Security:
+//   		oauth
 func deleteUser(w http.ResponseWriter, r *http.Request) {
 	// Set header
 	w.Header().Set("Content-Type", "application/json")

swagger.yaml

@@ -3,26 +3,460 @@ consumes:
     - application/json
 host: netmaker.io
 info:
-    description: Documentation of the Netmaker API.
+    description: |-
-    title: |-
+        API Usage
-        TODO update to follow actual info..  just set up enough to try out Swagger
+
-        Package classification Controller.
+        Most actions that can be performed via API can be performed via UI. We recommend managing your networks using the official netmaker-ui project. However, Netmaker can also be run without the UI, and all functions can be achieved via API calls. If your use case requires using Netmaker without the UI or you need to do some troubleshooting/advanced configuration, using the API directly may help.
+
+
+        Authentication
+
+        API calls must be authenticated via a header of the format -H “Authorization: Bearer <YOUR_SECRET_KEY>” There are two methods to obtain YOUR_SECRET_KEY: 1. Using the masterkey. By default, this value is “secret key,” but you should change this on your instance and keep it secure. This value can be set via env var at startup or in a config file (config/environments/< env >.yaml). See the [general usage](./USAGE.md) documentation for more details. 2. Using a JWT received for a node. This can be retrieved by calling the /api/nodes/<network>/authenticate endpoint, as documented below.
+    title: Controller.
     version: 1.0.0
 paths:
-    /api/networks:
+    /api/dns:
         get:
-            description: simple get all networks function
+            description: Gets all DNS entries
-            operationId: getNetworks
+            operationId: getAllDNS
+            schemes:
+                - https
+            tags:
+                - dns
+    /api/dns/{network}:
+        post:
+            description: Create a DNS entry
+            operationId: createDNS
+            schemes:
+                - https
+            tags:
+                - dns
+    /api/dns/{network}/{domain}:
+        delete:
+            description: Delete a DNS entry
+            operationId: deleteDNS
+            schemes:
+                - https
+            tags:
+                - dns
+    /api/dns/adm/{network}:
+        get:
+            description: Gets all DNS entries associated with the network
+            operationId: getDNS
+            schemes:
+                - https
+            tags:
+                - dns
+    /api/dns/adm/{network}/custom:
+        get:
+            description: Gets custom DNS entries associated with a network
+            operationId: getCustomDNS
+            schemes:
+                - https
+            tags:
+                - dns
+    /api/dns/adm/{network}/nodes:
+        get:
+            description: Gets node DNS entries associated with a network
+            operationId: getNodeDNS
+            schemes:
+                - https
+            tags:
+                - dns
+    /api/dns/adm/pushdns:
+        post:
+            description: Push DNS entries to nameserver
+            operationId: pushDNS
+            schemes:
+                - https
+            tags:
+                - dns
+    /api/extclients:
+        get:
+            operationId: getExtClient
+            schemes:
+                - https
+            summary: Get an individual extclient.
+            tags:
+                - ext_client
+    /api/extclients/{network}:
+        get:
+            description: |-
+                Get all extclients associated with network
+                Gets all extclients associated with network, including pending extclients
+            operationId: getNetworkExtClients
+            schemes:
+                - https
+            tags:
+                - ext_client
+    /api/extclients/{network}/{clientid}:
+        delete:
+            operationId: deleteExtClient
+            schemes:
+                - https
+            summary: Delete an individual extclient.
+            tags:
+                - ext_client
+        put:
+            operationId: updateExtClient
+            schemes:
+                - https
+            summary: Update an individual extclient.
+            tags:
+                - ext_client
+    /api/extclients/{network}/{clientid}/{type}:
+        get:
+            operationId: getExtClientConf
+            schemes:
+                - https
+            summary: Get an individual extclient.
+            tags:
+                - ext_client
+    /api/extclients/{network}/{nodeid}:
+        post:
+            operationId: createExtClient
+            schemes:
+                - https
+            summary: Create an individual extclient.  Must have valid key and be unique.
+            tags:
+                - ext_client
+    /api/getip:
+        get:
+            description: Get the current public IP address
+            operationId: getPublicIP
+            schemes:
+                - https
+            tags:
+                - ipservice
+    /api/networks:
+        get:
+            description: Get a network
+            operationId: getNetwork
             schemes:
                 - https
-            summary: Lists all networks
             tags:
                 - networks
+        post:
+            description: Create a network
+            operationId: createNetwork
+            schemes:
+                - https
+            tags:
+                - networks
+    /api/networks/{networkname}:
+        delete:
+            operationId: deleteNetwork
+            schemes:
+                - https
+            summary: Delete a network.  Will not delete if there are any nodes that belong to the network.
+            tags:
+                - networks
+        put:
+            description: Update a network
+            operationId: updateNetwork
+            schemes:
+                - https
+            tags:
+                - networks
+    /api/networks/{networkname}/acls:
+        get:
+            operationId: getNetworkACL
+            schemes:
+                - https
+            summary: Get a network ACL (Access Control List).
+            tags:
+                - networks
+        put:
+            operationId: updateNetworkACL
+            schemes:
+                - https
+            summary: Update a network ACL (Access Control List).
+            tags:
+                - networks
+    /api/networks/{networkname}/keys:
+        get:
+            operationId: getAccessKeys
+            schemes:
+                - https
+            summary: Get network access keys for a network.
+            tags:
+                - networks
+        post:
+            operationId: createAccessKey
+            schemes:
+                - https
+            summary: Create a network access key.
+            tags:
+                - networks
+    /api/networks/{networkname}/keys/{name}:
+        get:
+            operationId: deleteAccessKey
+            schemes:
+                - https
+            summary: Delete a network access key.
+            tags:
+                - networks
+    /api/networks/{networkname}/keyupdate:
+        post:
+            operationId: keyUpdate
+            schemes:
+                - https
+            summary: Update keys for a network.
+            tags:
+                - networks
+    /api/networks/{networkname}/nodelimit:
+        put:
+            description: Update a network's node limit
+            operationId: updateNetworkNodeLimit
+            schemes:
+                - https
+            tags:
+                - networks
+    /api/nodes:
+        get:
+            operationId: getAllNodes
+            schemes:
+                - https
+            summary: Get all nodes across all networks.
+            tags:
+                - nodes
+    /api/nodes/{network}:
+        get:
+            description: Gets all nodes associated with network including pending nodes
+            operationId: getNetworkNodes
+            schemes:
+                - https
+            tags:
+                - nodes
+        post:
+            operationId: createNode
+            schemes:
+                - https
+            summary: Create a node on a network.
+            tags:
+                - nodes
+    /api/nodes/{network}/{nodeid}:
+        delete:
+            operationId: deleteNode
+            schemes:
+                - https
+            summary: Delete an individual node.
+            tags:
+                - nodes
+        get:
+            operationId: getNode
+            schemes:
+                - https
+            summary: Get an individual node.
+            tags:
+                - nodes
+        put:
+            operationId: updateNode
+            schemes:
+                - https
+            summary: Update an individual node.
+            tags:
+                - nodes
+    /api/nodes/{network}/{nodeid}/approve:
+        post:
+            operationId: uncordonNode
+            schemes:
+                - https
+            security:
+                - TODO:
+                    - May
+            summary: Takes a node out of pending state.
+            tags:
+                - nodes
+    /api/nodes/{network}/{nodeid}/creategateway:
+        post:
+            operationId: createEgressGateway
+            schemes:
+                - https
+            summary: Create an egress gateway.
+            tags:
+                - nodes
+    /api/nodes/{network}/{nodeid}/createingress:
+        post:
+            operationId: createIngressGateway
+            schemes:
+                - https
+            summary: Create an ingress gateway.
+            tags:
+                - nodes
+    /api/nodes/{network}/{nodeid}/createrelay:
+        post:
+            operationId: createRelay
+            schemes:
+                - https
+            summary: Create a relay.
+            tags:
+                - nodes
+    /api/nodes/{network}/{nodeid}/deletegateway:
+        delete:
+            operationId: deleteEgressGateway
+            schemes:
+                - https
+            summary: Delete an egress gateway.
+            tags:
+                - nodes
+    /api/nodes/{network}/{nodeid}/deleteingress:
+        delete:
+            operationId: deleteIngressGateway
+            schemes:
+                - https
+            summary: Delete an ingress gateway.
+            tags:
+                - nodes
+    /api/nodes/{network}/{nodeid}/deleterelay:
+        delete:
+            operationId: deleteRelay
+            schemes:
+                - https
+            summary: Remove a relay.
+            tags:
+                - nodes
+    /api/nodes/adm/{network}/authenticate:
+        post:
+            operationId: authenticate
+            schemes:
+                - https
+            summary: Authenticate to make further API calls related to a network.
+            tags:
+                - nodes
+    /api/nodes/adm/{network}/lastmodified:
+        get:
+            operationId: getLastModified
+            schemes:
+                - https
+            security:
+                - TODO:
+                    - This
+                - Potential way to do this:
+                    - "On"
+                    - set
+            summary: Get the time that a network of nodes was last modified.
+            tags:
+                - nodes
+    /api/oauth/login:
+        get:
+            description: Handles OAuth login
+            operationId: HandleAuthLogin
+            schemes:
+                - https
+            tags:
+                - nodes
+    /api/server/getconfig:
+        get:
+            operationId: getConfig
+            schemes:
+                - https
+            summary: Get the server configuration.
+            tags:
+                - nodes
+    /api/server/getserverinfo:
+        get:
+            operationId: getServerInfo
+            schemes:
+                - https
+            summary: Get the server configuration.
+            tags:
+                - nodes
+    /api/server/register:
+        post:
+            description: Registers a client with the server and return the Certificate Authority and certificate
+            operationId: register
+            schemes:
+                - https
+            tags:
+                - nodes
+    /api/server/removenetwork/{network}:
+        delete:
+            operationId: removeNetwork
+            schemes:
+                - https
+            summary: Remove a network from the server.
+            tags:
+                - nodes
+    /api/users:
+        get:
+            description: Get all users
+            operationId: getUsers
+            schemes:
+                - https
+            tags:
+                - nodes
+    /api/users/{username}:
+        delete:
+            operationId: deleteUser
+            schemes:
+                - https
+            summary: Delete a user.
+            tags:
+                - nodes
+        get:
+            operationId: getUser
+            schemes:
+                - https
+            summary: Get an individual user.
+            tags:
+                - nodes
+        post:
+            operationId: createUser
+            schemes:
+                - https
+            summary: Create a user.
+            tags:
+                - nodes
+        put:
+            operationId: updateUser
+            schemes:
+                - https
+            summary: Update a user.
+            tags:
+                - nodes
+    /api/users/{username}/adm:
+        put:
+            description: Updates the given admin user's info (as long as the user is an admin)
+            operationId: updateUserAdm
+            schemes:
+                - https
+            tags:
+                - nodes
+    /api/users/adm/authenticate:
+        post:
+            operationId: authenticateUser
+            schemes:
+                - https
+            summary: Node authenticates using its password and retrieves a JWT for authorization.
+            tags:
+                - nodes
+    /api/users/adm/createadmin:
+        post:
+            operationId: createAdmin
+            schemes:
+                - https
+            summary: Make a user an admin.
+            tags:
+                - nodes
+    /api/users/adm/hasadmin:
+        get:
+            operationId: hasAdmin
+            schemes:
+                - https
+            summary: Checks whether the server has an admin.
+            tags:
+                - nodes
+    /api/users/networks/{username}:
+        put:
+            description: Updates the networks of the given user
+            operationId: updateUserNetworks
+            schemes:
+                - https
+            tags:
+                - nodes
 produces:
     - application/json
 schemes:
-    - http
+    - https
-securityDefinitions:
-    basic:
-        type: basic
 swagger: "2.0"