docs: Applications

coder · mtojek · Dec 21, 2022 · Dec 20, 2022 · Dec 20, 2022 · Dec 20, 2022
commit ffc17487c6934ef077273668d3b9092924ce31c5
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
@@ -25,6 +25,61 @@ const docTemplate = `{
     "host": "{{.Host}}",
     "basePath": "{{.BasePath}}",
     "paths": {
+        "/applications/auth-redirect": {
+            "get": {
+                "security": [
+                    {
+                        "CoderSessionToken": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Applications"
+                ],
+                "summary": "Redirect to URI with encrypted API key",
+                "operationId": "redirect-to-uri-with-encrypted-api-key",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Redirect destination",
+                        "name": "redirect_uri",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "307": {
+                        "description": "Temporary Redirect"
+                    }
+                }
+            }
+        },
+        "/applications/host": {
+            "get": {
+                "security": [
+                    {
+                        "CoderSessionToken": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Applications"
+                ],
+                "summary": "Get applications host",
+                "operationId": "get-app-host",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.GetAppHostResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/organizations/{organization-id}/templates/": {
             "post": {
                 "security": [
@@ -712,6 +767,15 @@ const docTemplate = `{
                 }
             }
         },
+        "codersdk.GetAppHostResponse": {
+            "type": "object",
+            "properties": {
+                "host": {
+                    "description": "Host is the externally accessible URL for the Coder instance.",
+                    "type": "string"
+                }
+            }
+        },
         "codersdk.Healthcheck": {
             "type": "object",
             "properties": {

diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
@@ -17,6 +17,53 @@
   },
   "basePath": "/api/v2",
   "paths": {
+    "/applications/auth-redirect": {
+      "get": {
+        "security": [
+          {
+            "CoderSessionToken": []
+          }
+        ],
+        "produces": ["application/json"],
+        "tags": ["Applications"],
+        "summary": "Redirect to URI with encrypted API key",
+        "operationId": "redirect-to-uri-with-encrypted-api-key",
+        "parameters": [
+          {
+            "type": "string",
+            "description": "Redirect destination",
+            "name": "redirect_uri",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "307": {
+            "description": "Temporary Redirect"
+          }
+        }
+      }
+    },
+    "/applications/host": {
+      "get": {
+        "security": [
+          {
+            "CoderSessionToken": []
+          }
+        ],
+        "produces": ["application/json"],
+        "tags": ["Applications"],
+        "summary": "Get applications host",
+        "operationId": "get-app-host",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "$ref": "#/definitions/codersdk.GetAppHostResponse"
+            }
+          }
+        }
+      }
+    },
     "/organizations/{organization-id}/templates/": {
       "post": {
         "security": [
@@ -635,6 +682,15 @@
         }
       }
     },
+    "codersdk.GetAppHostResponse": {
+      "type": "object",
+      "properties": {
+        "host": {
+          "description": "Host is the externally accessible URL for the Coder instance.",
+          "type": "string"
+        }
+      }
+    },
     "codersdk.Healthcheck": {
       "type": "object",
       "properties": {

diff --git a/coderd/workspaceapps.go b/coderd/workspaceapps.go
@@ -56,6 +56,13 @@ var nonCanonicalHeaders = map[string]string{
 	"Sec-Websocket-Version":    "Sec-WebSocket-Version",
 }
 
+// @Summary Get applications host
+// @ID get-app-host
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Applications
+// @Success 200 {object} codersdk.GetAppHostResponse
+// @Router /applications/host [get]
 func (api *API) appHost(rw http.ResponseWriter, r *http.Request) {
 	host := api.AppHostname
 	if host != "" && api.AccessURL.Port() != "" {
@@ -484,6 +491,15 @@ func (api *API) verifyWorkspaceApplicationSubdomainAuth(rw http.ResponseWriter,
 	return false
 }
 
+// @Summary Redirect to URI with encrypted API key
+// @ID redirect-to-uri-with-encrypted-api-key
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Applications
+// @Param redirect_uri query string false "Redirect destination"
+// @Success 307
+// @Router /applications/auth-redirect [get]
+//
 // workspaceApplicationAuth is an endpoint on the main router that handles
 // redirects from the subdomain handler.
 //

diff --git a/codersdk/workspaces.go b/codersdk/workspaces.go
@@ -350,6 +350,7 @@ func (c *Client) WorkspaceByOwnerAndName(ctx context.Context, owner string, name
 }
 
 type GetAppHostResponse struct {
+	// Host is the externally accessible URL for the Coder instance.
 	Host string `json:"host"`
 }
 

diff --git a/docs/api/applications.md b/docs/api/applications.md
@@ -0,0 +1,62 @@
+# Applications
+
+> This page is incomplete, stay tuned.
+
+## Redirect to URI with encrypted API key
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X GET http://coder-server:8080/api/v2/applications/auth-redirect \
+  -H 'Coder-Session-Token: API_KEY'
+
+```
+
+`GET /applications/auth-redirect`
+
+### Parameters
+
+| Name         | In    | Type   | Required | Description          |
+| ------------ | ----- | ------ | -------- | -------------------- |
+| redirect_uri | query | string | false    | Redirect destination |
+
+### Responses
+
+| Status | Meaning                                                                 | Description        | Schema    |
+| ------ | ----------------------------------------------------------------------- | ------------------ | --------- |
+| 307    | [Temporary Redirect](https://tools.ietf.org/html/rfc7231#section-6.4.7) | Temporary Redirect | no schema |
+
+To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
+
+## Get applications host
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X GET http://coder-server:8080/api/v2/applications/host \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+
+```
+
+`GET /applications/host`
+
+### Example responses
+
+> 200 Response
+
+```json
+{
+  "host": "string"
+}
+```
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema                                                               |
+| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.GetAppHostResponse](schemas.md#codersdkgetapphostresponse) |
+
+To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
diff --git a/docs/api/schemas.md b/docs/api/schemas.md
@@ -84,6 +84,20 @@
 | `latency_ms` | number  | false    | none         | none        |
 | `preferred`  | boolean | false    | none         | none        |
 
+## codersdk.GetAppHostResponse
+
+```json
+{
+  "host": "string"
+}
+```
+
+### Properties
+
+| Name   | Type   | Required | Restrictions | Description                                                   |
+| ------ | ------ | -------- | ------------ | ------------------------------------------------------------- |
+| `host` | string | false    | none         | Host is the externally accessible URL for the Coder instance. |
+
 ## codersdk.Healthcheck
 
 ```json

diff --git a/docs/manifest.json b/docs/manifest.json
@@ -329,6 +329,10 @@
           "title": "Authentication",
           "path": "./api/authentication.md"
         },
+        {
+          "title": "Applications",
+          "path": "./api/applications.md"
+        },
         {
           "title": "Templates",
           "path": "./api/templates.md"
-Original file line number
+Diff line change
@@ Expand Up @@
     }
     type GetAppHostResponse struct {
+    	// Host is the externally accessible URL for the Coder instance.
     	Host string `json:"host"`
     }
@@ Expand Down @@