APPS-9908 Add docs for exec endpoint (#945)

* APPS-9908 Add docs for exec endpoint

* update wording

specification/DigitalOcean-public.v2.yaml

@@ -553,6 +553,10 @@ paths:
     get:
       $ref: 'resources/apps/apps_get_logs_active_deployment.yml'
 
+  /v2/apps/{app_id}/components/{component_name}/exec:
+    get:
+      $ref: 'resources/apps/apps_get_exec_active_deployment.yml'
+
   /v2/apps/{app_id}/deployments:
     get:
       $ref: 'resources/apps/apps_list_deployments.yml'
@@ -575,6 +579,10 @@ paths:
     get:
       $ref: 'resources/apps/apps_get_logs_aggregate.yml'
 
+  /v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/exec:
+    get:
+      $ref: 'resources/apps/apps_get_exec.yml'
+
   /v2/apps/{app_id}/logs:
     get:
       $ref: 'resources/apps/apps_get_logs_active_deployment_aggregate.yml'

specification/resources/apps/apps_get_exec.yml

@@ -0,0 +1,42 @@
+operationId: apps_get_exec
+
+summary: Retrieve Exec URL for Deployment
+
+description:
+  Returns a websocket URL that allows sending/receiving console input and output
+  to a component of the specified deployment if one exists.
+
+tags:
+  - Apps
+
+parameters:
+  - $ref: parameters.yml#/app_id
+  - $ref: parameters.yml#/deployment_id
+  - $ref: parameters.yml#/component
+
+responses:
+  "200":
+    $ref: responses/get_exec.yml
+
+  "401":
+    $ref: ../../shared/responses/unauthorized.yml
+
+  "404":
+    $ref: "../../shared/responses/not_found.yml"
+
+  "429":
+    $ref: "../../shared/responses/too_many_requests.yml"
+
+  "500":
+    $ref: ../../shared/responses/server_error.yml
+
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+
+x-codeSamples:
+  - $ref: "examples/curl/apps_get_exec.yml"
+  - $ref: "examples/python/apps_get_exec.yml"
+
+security:
+  - bearer_auth:
+      - "app:update"

specification/resources/apps/apps_get_exec_active_deployment.yml

@@ -0,0 +1,41 @@
+operationId: apps_get_exec_active_deployment
+
+summary: Retrieve Exec URL
+
+description:
+  Returns a websocket URL that allows sending/receiving console input and output
+  to a component of the active deployment if one exists.
+
+tags:
+  - Apps
+
+parameters:
+  - $ref: parameters.yml#/app_id
+  - $ref: parameters.yml#/component
+
+responses:
+  "200":
+    $ref: responses/get_exec.yml
+
+  "401":
+    $ref: ../../shared/responses/unauthorized.yml
+
+  "404":
+    $ref: "../../shared/responses/not_found.yml"
+
+  "429":
+    $ref: "../../shared/responses/too_many_requests.yml"
+
+  "500":
+    $ref: ../../shared/responses/server_error.yml
+
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+
+x-codeSamples:
+  - $ref: "examples/curl/apps_get_exec_active_deployment.yml"
+  - $ref: "examples/python/apps_get_exec_active_deployment.yml"
+
+security:
+  - bearer_auth:
+      - "app:update"

specification/resources/apps/examples/curl/apps_get_exec.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/exec"

specification/resources/apps/examples/curl/apps_get_exec_active_deployment.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/apps/{app_id}/components/{component_name}/exec"

specification/resources/apps/examples/python/apps_get_exec.yml

@@ -0,0 +1,8 @@
+lang: Python
+source: |-
+  import os
+  from pydo import Client
+
+  client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
+
+  get_resp = client.apps.get_exec(app_id="4f6c71e2", deployment_id="3aa4d20e", component_name="component")

specification/resources/apps/examples/python/apps_get_exec_active_deployment.yml

@@ -0,0 +1,8 @@
+lang: Python
+source: |-
+  import os
+  from pydo import Client
+
+  client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
+
+  get_resp = client.apps.get_exec_active_deployment(app_id="a6adf840", component_name="component")

specification/resources/apps/models/apps_get_exec_response.yml

@@ -0,0 +1,6 @@
+properties:
+  url:
+    description: A websocket URL that allows sending/receiving console input and receiving console output.
+    type: string
+    example: wss://exec/?token=xxx
+type: object

specification/resources/apps/responses/examples.yml

@@ -599,6 +599,10 @@ logs:
     historic_logs:
       - https://logs-example/archive/build.log
 
+exec:
+  value:
+    url: wss://exec/?token=xxx
+
 regions:
   value:
     regions:

specification/resources/apps/responses/get_exec.yml

@@ -0,0 +1,17 @@
+description: A JSON object with a websocket URL that allows sending/receiving console input and output.
+
+content:
+  application/json:
+    schema:
+      $ref: ../models/apps_get_exec_response.yml
+    examples:
+      exec:
+        $ref: examples.yml#/exec
+
+headers:
+  ratelimit-limit:
+    $ref: ../../../shared/headers.yml#/ratelimit-limit
+  ratelimit-remaining:
+    $ref: ../../../shared/headers.yml#/ratelimit-remaining
+  ratelimit-reset:
+    $ref: ../../../shared/headers.yml#/ratelimit-reset