Scaffold autoscaler openapi spec (#949)

* Scaffold droplet autoscaler spec

* Address peer review comments

* Address copy changes

* clean linter errors

* Address copy comments p2

* rename to droplet autoscale pools

* Address open PR comments

* Address last couple of comments and add some recent dev changes

---------

Co-authored-by: Anna Lushnikova <loosla@users.noreply.github.com>

specification/DigitalOcean-public.v2.yaml

@@ -228,6 +228,10 @@ tags:
       types. Find more information about each of these objects in their
       respective sections.
 
+  - name: Droplet Autoscale Pools
+    description: |-
+      Droplet autoscale pools manage automatic horizontal scaling for your applications based on resource usage (CPU, memory, or both) or a static configuration.
+
   - name: Firewalls
     description: |-
       [DigitalOcean Cloud Firewalls](https://docs.digitalocean.com/products/networking/firewalls/)
@@ -998,6 +1002,32 @@ paths:
     post:
       $ref: 'resources/droplets/droplets_destroy_retryWithAssociatedResources.yml'
 
+  /v2/droplets/autoscale:
+    get:
+      $ref: 'resources/autoscale_pools/autoscale_pool_list.yml'
+    post:
+      $ref: 'resources/autoscale_pools/autoscale_pool_create.yml'
+
+  /v2/droplets/autoscale/{autoscale_pool_id}:
+    get:
+      $ref: 'resources/autoscale_pools/autoscale_pool_get.yml'
+    put:
+      $ref: 'resources/autoscale_pools/autoscale_pool_update.yml'
+    delete:
+      $ref: 'resources/autoscale_pools/autoscale_pool_delete.yml'
+
+  /v2/droplets/autoscale/{autoscale_pool_id}/dangerous:
+    delete:
+      $ref: 'resources/autoscale_pools/autoscale_pool_delete_dangerous.yml'
+
+  /v2/droplets/autoscale/{autoscale_pool_id}/members:
+    get:
+      $ref: 'resources/autoscale_pools/autoscale_pool_list_members.yml'
+
+  /v2/droplets/autoscale/{autoscale_pool_id}/history:
+    get:
+      $ref: 'resources/autoscale_pools/autoscale_pool_list_history.yml'
+
   /v2/firewalls:
     get:
       $ref: 'resources/firewalls/firewalls_list.yml'

specification/resources/autoscale_pools/autoscale_pool_create.yml

@@ -0,0 +1,45 @@
+operationId: autoscalepools_create
+
+summary: Create a New Autoscale Pool
+
+description: |
+  To create a new autoscale pool, send a POST request to `/v2/droplets/autoscale` setting the required attributes.
+
+  The response body will contain a JSON object with a key called `autoscale_pool` containing the standard attributes for the new autoscale pool.
+
+tags:
+  - Droplet Autoscale Pools
+
+requestBody:
+  content:
+    application/json:
+      schema:
+        $ref: 'models/autoscale_pool_create.yml'
+      examples:
+        Autoscale Create Request Dynamic Config:
+          $ref: 'examples.yml#/autoscale_create_request_dynamic'
+        Autoscale Create Request Static Config:
+          $ref: 'examples.yml#/autoscale_create_request_static'
+
+responses:
+  '202':
+    $ref: 'responses/autoscale_pool_create.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.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/autoscale_pool_create.yml'
+
+security:
+  - bearer_auth:
+      - 'droplet:create'

specification/resources/autoscale_pools/autoscale_pool_delete.yml

@@ -0,0 +1,40 @@
+operationId: autoscalepools_delete
+
+summary: Delete autoscale pool
+
+description: |
+  To destroy an autoscale pool, send a DELETE request to the `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID` endpoint.
+
+  A successful response will include a 202 response code and no content. 
+
+tags:
+  - Droplet Autoscale Pools
+
+parameters:
+  - $ref: 'parameters.yml#/autoscale_pool_id'
+
+responses:
+  '202':
+    $ref: '../../shared/responses/no_content.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/autoscale_pool_delete.yml'
+
+security:
+  - bearer_auth:
+    - 'droplet:delete'

specification/resources/autoscale_pools/autoscale_pool_delete_dangerous.yml

@@ -0,0 +1,40 @@
+operationId: autoscalepools_delete_dangerous
+
+summary: Delete autoscale pool and resources
+
+description: |
+  To destroy an autoscale pool and its associated resources (Droplets),
+  send a DELETE request to the `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID/dangerous` endpoint.
+
+tags:
+  - Droplet Autoscale Pools
+
+parameters:
+  - $ref: 'parameters.yml#/autoscale_pool_id'
+  - $ref: 'parameters.yml#/x_dangerous'
+
+responses:
+  '202':
+    $ref: '../../shared/responses/no_content.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/autoscale_pool_delete_dangerous.yml'
+
+security:
+  - bearer_auth:
+    - 'droplet:delete'

specification/resources/autoscale_pools/autoscale_pool_get.yml

@@ -0,0 +1,39 @@
+operationId: autoscalepools_get
+
+summary: Retrieve an Existing Autoscale Pool
+
+description: |
+  To show information about an individual autoscale pool, send a GET request to
+  `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID`.
+
+tags:
+  - Droplet Autoscale Pools
+
+parameters:
+  - $ref: 'parameters.yml#/autoscale_pool_id'
+
+responses:
+  '200':
+    $ref: 'responses/existing_autoscale_pool.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/autoscale_pool_get.yml'
+
+security:
+  - bearer_auth:
+    - 'droplet:read'

specification/resources/autoscale_pools/autoscale_pool_list.yml

@@ -0,0 +1,40 @@
+operationId: autoscalepools_list
+
+summary: List All Autoscale Pools
+
+description: |
+  To list all autoscale pools in your team, send a GET request to `/v2/droplets/autoscale`.
+  The response body will be a JSON object with a key of `autoscale_pools` containing an array of autoscale pool objects.
+  These each contain the standard autoscale pool attributes.
+
+tags:
+  - Droplet Autoscale Pools
+
+parameters:
+  - $ref: '../../shared/parameters.yml#/per_page'
+  - $ref: '../../shared/parameters.yml#/page'
+  - $ref: './parameters.yml#/autoscale_pool_name'
+
+responses:
+  '200':
+    $ref: 'responses/all_autoscale_pools.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.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/autoscale_pools_list.yml'
+
+
+security:
+  - bearer_auth:
+    - 'droplet:read'

specification/resources/autoscale_pools/autoscale_pool_list_history.yml

@@ -0,0 +1,44 @@
+operationId: autoscalepools_list_history
+
+summary: List history events
+
+description: |
+  To list all of the scaling history events of an autoscale pool, send a GET request to `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID/history`.
+
+  The response body will be a JSON object with a key of `history`. This will be
+  set to an array containing objects each representing a history event. 
+
+tags:
+  - Droplet Autoscale Pools
+
+parameters:
+  - $ref: '../../shared/parameters.yml#/per_page'
+  - $ref: '../../shared/parameters.yml#/page'
+  - $ref: 'parameters.yml#/autoscale_pool_id'
+
+responses:
+  '200':
+    $ref: 'responses/history_events.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/autoscale_pool_history_events.yml'
+
+
+security:
+  - bearer_auth:
+    - 'droplet:read'

specification/resources/autoscale_pools/autoscale_pool_list_members.yml

@@ -0,0 +1,44 @@
+operationId: autoscalepools_list_members
+
+summary: List members
+
+description: |
+  To list the Droplets in an autoscale pool, send a GET request to `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID/members`.
+
+  The response body will be a JSON object with a key of `droplets`. This will be
+  set to an array containing information about each of the Droplets in the autoscale pool.
+
+tags:
+  - Droplet Autoscale Pools
+
+parameters:
+  - $ref: '../../shared/parameters.yml#/per_page'
+  - $ref: '../../shared/parameters.yml#/page'
+  - $ref: 'parameters.yml#/autoscale_pool_id'
+
+responses:
+  '200':
+    $ref: 'responses/all_members.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/autoscale_pool_members.yml'
+
+
+security:
+  - bearer_auth:
+    - 'droplet:read'

specification/resources/autoscale_pools/autoscale_pool_update.yml

@@ -0,0 +1,49 @@
+operationId: autoscalepools_update
+
+summary: Update Autoscale Pool
+
+description: |
+  To update the configuration of an existing autoscale pool, send a PUT request to
+  `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID`. The request must contain a full representation
+  of the autoscale pool including existing attributes. 
+
+tags:
+  - Droplet Autoscale Pools
+
+parameters:
+  - $ref: 'parameters.yml#/autoscale_pool_id'
+
+requestBody:
+  content:
+    application/json:
+      schema:
+        $ref: 'models/autoscale_pool_create.yml'
+      examples:
+        Autoscale Update Request:
+          $ref: 'examples.yml#/autoscale_update_request'
+
+responses:
+  '200':
+    $ref: 'responses/autoscale_pool_create.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/autoscale_pool_update.yml'
+
+security:
+  - bearer_auth:
+    - 'droplet:create'