Add swagger docs for host preflights api endpoints (#2216)

Author: sgalsaleh

api/docs/docs.go

@@ -1,8 +1,8 @@
 {
-    "components": {"schemas":{"types.APIError":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/types.APIError"},"type":"array","uniqueItems":false},"field":{"type":"string"},"message":{"type":"string"},"status_code":{"type":"integer"}},"type":"object"},"types.AuthRequest":{"properties":{"password":{"type":"string"}},"type":"object"},"types.AuthResponse":{"properties":{"token":{"type":"string"}},"type":"object"},"types.Health":{"properties":{"status":{"type":"string"}},"type":"object"},"types.Install":{"properties":{"config":{"$ref":"#/components/schemas/types.InstallationConfig"},"status":{"$ref":"#/components/schemas/types.InstallationStatus"}},"type":"object"},"types.InstallationConfig":{"properties":{"adminConsolePort":{"type":"integer"},"dataDirectory":{"type":"string"},"globalCidr":{"type":"string"},"httpProxy":{"type":"string"},"httpsProxy":{"type":"string"},"localArtifactMirrorPort":{"type":"integer"},"networkInterface":{"type":"string"},"noProxy":{"type":"string"},"podCidr":{"type":"string"},"serviceCidr":{"type":"string"}},"type":"object"},"types.InstallationState":{"type":"string","x-enum-varnames":["InstallationStatePending","InstallationStateRunning","InstallationStateSucceeded","InstallationStateFailed"]},"types.InstallationStatus":{"properties":{"description":{"type":"string"},"lastUpdated":{"type":"string"},"state":{"$ref":"#/components/schemas/types.InstallationState"}},"type":"object"}},"securitySchemes":{"bearerauth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"}}},
+    "components": {"schemas":{"types.APIError":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/types.APIError"},"type":"array","uniqueItems":false},"field":{"type":"string"},"message":{"type":"string"},"status_code":{"type":"integer"}},"type":"object"},"types.AuthRequest":{"properties":{"password":{"type":"string"}},"type":"object"},"types.AuthResponse":{"properties":{"token":{"type":"string"}},"type":"object"},"types.Health":{"properties":{"status":{"type":"string"}},"type":"object"},"types.HostPreflightOutput":{"properties":{"fail":{"items":{"$ref":"#/components/schemas/types.HostPreflightRecord"},"type":"array","uniqueItems":false},"pass":{"items":{"$ref":"#/components/schemas/types.HostPreflightRecord"},"type":"array","uniqueItems":false},"warn":{"items":{"$ref":"#/components/schemas/types.HostPreflightRecord"},"type":"array","uniqueItems":false}},"type":"object"},"types.HostPreflightRecord":{"properties":{"message":{"type":"string"},"title":{"type":"string"}},"type":"object"},"types.HostPreflightState":{"type":"string","x-enum-varnames":["HostPreflightStatePending","HostPreflightStateRunning","HostPreflightStateSucceeded","HostPreflightStateFailed"]},"types.HostPreflightStatus":{"properties":{"description":{"type":"string"},"lastUpdated":{"type":"string"},"state":{"$ref":"#/components/schemas/types.HostPreflightState"}},"type":"object"},"types.HostPreflightStatusResponse":{"properties":{"output":{"$ref":"#/components/schemas/types.HostPreflightOutput"},"status":{"$ref":"#/components/schemas/types.HostPreflightStatus"}},"type":"object"},"types.Install":{"properties":{"config":{"$ref":"#/components/schemas/types.InstallationConfig"},"status":{"$ref":"#/components/schemas/types.InstallationStatus"}},"type":"object"},"types.InstallationConfig":{"properties":{"adminConsolePort":{"type":"integer"},"dataDirectory":{"type":"string"},"globalCidr":{"type":"string"},"httpProxy":{"type":"string"},"httpsProxy":{"type":"string"},"localArtifactMirrorPort":{"type":"integer"},"networkInterface":{"type":"string"},"noProxy":{"type":"string"},"podCidr":{"type":"string"},"serviceCidr":{"type":"string"}},"type":"object"},"types.InstallationState":{"type":"string","x-enum-varnames":["InstallationStatePending","InstallationStateRunning","InstallationStateSucceeded","InstallationStateFailed"]},"types.InstallationStatus":{"properties":{"description":{"type":"string"},"lastUpdated":{"type":"string"},"state":{"$ref":"#/components/schemas/types.InstallationState"}},"type":"object"},"types.RunHostPreflightResponse":{"properties":{"status":{"$ref":"#/components/schemas/types.HostPreflightStatus"}},"type":"object"}},"securitySchemes":{"bearerauth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"}}},
     "info": {"contact":{"email":"support@replicated.com","name":"API Support","url":"https://github.com/replicatedhq/embedded-cluster/issues"},"description":"This is the API for the Embedded Cluster project.","license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"},"termsOfService":"http://swagger.io/terms/","title":"Embedded Cluster API","version":"0.1"},
     "externalDocs": {"description":"OpenAPI","url":"https://swagger.io/resources/open-api/"},
-    "paths": {"/auth/login":{"post":{"description":"Authenticate a user","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.AuthRequest"}}},"description":"Auth Request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.AuthResponse"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.APIError"}}},"description":"Unauthorized"}},"summary":"Authenticate a user","tags":["auth"]}},"/health":{"get":{"description":"get the health of the API","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.Health"}}},"description":"OK"}},"summary":"Get the health of the API","tags":["health"]}},"/install":{"get":{"description":"get the install object","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.Install"}}},"description":"OK"}},"security":[{"bearerauth":[]}],"summary":"Get the install object","tags":["install"]}}},
+    "paths": {"/auth/login":{"post":{"description":"Authenticate a user","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.AuthRequest"}}},"description":"Auth Request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.AuthResponse"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.APIError"}}},"description":"Unauthorized"}},"summary":"Authenticate a user","tags":["auth"]}},"/health":{"get":{"description":"get the health of the API","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.Health"}}},"description":"OK"}},"summary":"Get the health of the API","tags":["health"]}},"/install":{"get":{"description":"get the install object","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.Install"}}},"description":"OK"}},"security":[{"bearerauth":[]}],"summary":"Get the install object","tags":["install"]}},"/install/host-preflights":{"get":{"description":"Get the current status and results of host preflight checks","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.HostPreflightStatusResponse"}}},"description":"OK"}},"security":[{"bearerauth":[]}],"summary":"Get host preflight status","tags":["install"]},"post":{"description":"Run install host preflight checks using installation config and client-provided data","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.RunHostPreflightResponse"}}},"description":"OK"}},"security":[{"bearerauth":[]}],"summary":"Run install host preflight checks","tags":["install"]}}},
     "openapi": "3.1.0",
     "servers": [
         {"url":"/api"}

api/docs/swagger.json

@@ -29,6 +29,54 @@ components:
         status:
           type: string
       type: object
+    types.HostPreflightOutput:
+      properties:
+        fail:
+          items:
+            $ref: '#/components/schemas/types.HostPreflightRecord'
+          type: array
+          uniqueItems: false
+        pass:
+          items:
+            $ref: '#/components/schemas/types.HostPreflightRecord'
+          type: array
+          uniqueItems: false
+        warn:
+          items:
+            $ref: '#/components/schemas/types.HostPreflightRecord'
+          type: array
+          uniqueItems: false
+      type: object
+    types.HostPreflightRecord:
+      properties:
+        message:
+          type: string
+        title:
+          type: string
+      type: object
+    types.HostPreflightState:
+      type: string
+      x-enum-varnames:
+      - HostPreflightStatePending
+      - HostPreflightStateRunning
+      - HostPreflightStateSucceeded
+      - HostPreflightStateFailed
+    types.HostPreflightStatus:
+      properties:
+        description:
+          type: string
+        lastUpdated:
+          type: string
+        state:
+          $ref: '#/components/schemas/types.HostPreflightState'
+      type: object
+    types.HostPreflightStatusResponse:
+      properties:
+        output:
+          $ref: '#/components/schemas/types.HostPreflightOutput'
+        status:
+          $ref: '#/components/schemas/types.HostPreflightStatus'
+      type: object
     types.Install:
       properties:
         config:
@@ -75,6 +123,11 @@ components:
         state:
           $ref: '#/components/schemas/types.InstallationState'
       type: object
+    types.RunHostPreflightResponse:
+      properties:
+        status:
+          $ref: '#/components/schemas/types.HostPreflightStatus'
+      type: object
   securitySchemes:
     bearerauth:
       bearerFormat: JWT
@@ -151,5 +204,35 @@ paths:
       summary: Get the install object
       tags:
       - install
+  /install/host-preflights:
+    get:
+      description: Get the current status and results of host preflight checks
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/types.HostPreflightStatusResponse'
+          description: OK
+      security:
+      - bearerauth: []
+      summary: Get host preflight status
+      tags:
+      - install
+    post:
+      description: Run install host preflight checks using installation config and
+        client-provided data
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/types.RunHostPreflightResponse'
+          description: OK
+      security:
+      - bearerauth: []
+      summary: Run install host preflight checks
+      tags:
+      - install
 servers:
 - url: /api

api/docs/swagger.yaml

@@ -76,3 +76,29 @@ func (a *API) getInstallStatus(w http.ResponseWriter, r *http.Request) {
 
 	a.json(w, r, http.StatusOK, status)
 }
+
+// runInstallHostPreflights handler to run install host preflight checks
+//
+//	@Summary		Run install host preflight checks
+//	@Description	Run install host preflight checks using installation config and client-provided data
+//	@Tags			install
+//	@Security		bearerauth
+//	@Produce		json
+//	@Success		200	{object}	types.RunHostPreflightResponse
+//	@Router			/install/host-preflights [post]
+func (a *API) runInstallHostPreflights(w http.ResponseWriter, r *http.Request) {
+	// TODO: implement
+}
+
+// getInstallHostPreflightStatus handler to get host preflight status
+//
+//	@Summary		Get host preflight status
+//	@Description	Get the current status and results of host preflight checks
+//	@Tags			install
+//	@Security		bearerauth
+//	@Produce		json
+//	@Success		200	{object}	types.HostPreflightStatusResponse
+//	@Router			/install/host-preflights [get]
+func (a *API) getInstallHostPreflightStatus(w http.ResponseWriter, r *http.Request) {
+	// TODO: implement
+}