diff --git a/auth/auth.go b/auth/auth.go index 52065037..a8572120 100644 --- a/auth/auth.go +++ b/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") diff --git a/controllers/dns.go b/controllers/dns.go index b808cec2..64e445f1 100644 --- a/controllers/dns.go +++ b/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") diff --git a/controllers/docs.go b/controllers/docs.go index 18fcffe2..8467b026 100644 --- a/controllers/docs.go +++ b/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 ” 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//authenticate endpoint, as documented below. // // Schemes: https // BasePath: / @@ -17,9 +23,5 @@ // Security: // - oauth // -// SecurityDefinitions: -// basic: -// type: basic -// // swagger:meta package controller diff --git a/controllers/ext_client.go b/controllers/ext_client.go index e5c19e82..aab36705 100644 --- a/controllers/ext_client.go +++ b/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. -//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 +// swagger:route GET /api/extclients ext_client getAllExtClients +// +// 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) } -/** - * To create a extclient - * Must have valid key and be unique - */ +// swagger:route POST /api/extclients/{network}/{nodeid} ext_client createExtClient +// +// 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 -//Pretty straightforward +// swagger:route DELETE /api/extclients/{network}/{clientid} ext_client deleteExtClient +// +// 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") diff --git a/controllers/ipservice.go b/controllers/ipservice.go index 6ca80e39..d237ab37 100644 --- a/controllers/ipservice.go +++ b/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) diff --git a/controllers/network.go b/controllers/network.go index fbb27270..9179d271 100644 --- a/controllers/network.go +++ b/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 -// Will stop you if there's any nodes associated +// swagger:route DELETE /api/networks/{networkname} networks deleteNetwork +// +// 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") diff --git a/controllers/node.go b/controllers/node.go index fda392ff..7b1ed28d 100644 --- a/controllers/node.go +++ b/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") diff --git a/controllers/relay.go b/controllers/relay.go index e7e05758..6c5ad1a0 100644 --- a/controllers/relay.go +++ b/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) diff --git a/controllers/server.go b/controllers/server.go index 55b3a997..0ce49e4a 100644 --- a/controllers/server.go +++ b/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") diff --git a/controllers/user.go b/controllers/user.go index 1a0e42bc..48872918 100644 --- a/controllers/user.go +++ b/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") diff --git a/swagger.yaml b/swagger.yaml index 6c799c19..0a0750b5 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -3,26 +3,460 @@ consumes: - application/json host: netmaker.io info: - description: Documentation of the Netmaker API. - title: |- - TODO update to follow actual info.. just set up enough to try out Swagger - Package classification Controller. + description: |- + 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 ” 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//authenticate endpoint, as documented below. + title: Controller. version: 1.0.0 paths: - /api/networks: + /api/dns: get: - description: simple get all networks function - operationId: getNetworks + description: Gets all DNS entries + 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 -securityDefinitions: - basic: - type: basic + - https swagger: "2.0"