Apply suggestions from code review

Co-authored-by: Dan Brian <[email protected]>

specification/DigitalOcean-public.v2.yaml

@@ -467,9 +467,9 @@ tags:
 
   - name: Spaces Keys
     description: |-
-      Spaces keys are used to authenticate requests to DigitalOcean Spaces Buckets. By
-      sending requests to the `/v2/spaces/keys` endpoint, you can list, create, or
-      update, delete Spaces keys.
+      Spaces keys authenticate requests to DigitalOcean Spaces Buckets.
+      You can create, list, update, or delete Spaces keys by sending requests to
+      to the `/v2/spaces/keys` endpoint.
 
   - name: SSH Keys
     description: Manage SSH keys available on your account.

specification/resources/spaces/key_create.yml

@@ -3,7 +3,8 @@ operationId: spacesKey_create
 summary: "[Beta] Create a New Spaces Access Key"
 
 description: |
-  To create a new Spaces Access Key, send a POST request to `/v2/spaces/keys`.
+  To create a new Spaces Access Key, send a POST request to `/v2/spaces/keys`. 
+  At the moment, you cannot mix a fullaccess permission with scoped permissions.
 
 tags:
   - Spaces Keys
@@ -50,7 +51,7 @@ responses:
     $ref: 'responses/key_create.yml'
 
   '400':
-    $ref: '../../shared/responses/bad_request.yml'
+    $ref: 'responses/bad_request.yml'
 
   '401':
     $ref: '../../shared/responses/unauthorized.yml'

specification/resources/spaces/key_delete.yml

@@ -5,6 +5,8 @@ summary: "[Beta] Delete a Spaces Access Key"
 description: |
   To delete a Spaces Access Key, send a DELETE request to `/v2/spaces/keys/$ACCESS_KEY`.
 
+  A successful request will return a `204 No Content` status code.
+
 tags:
   - Spaces Keys
 

specification/resources/spaces/key_patch.yml

@@ -3,7 +3,8 @@ operationId: spacesKey_patch
 summary: "[Beta] Update Spaces Access Keys"
 
 description: |
-  To update Spaces Access Key, send a PUT or PATCH request to `/v2/spaces/keys/$ACCESS_KEY`.
+  To update Spaces Access Key, send a PUT or PATCH request to `/v2/spaces/keys/$ACCESS_KEY`. At the moment, you cannot convert a
+  fullaccess key to a scoped key or vice versa. You can only update the name of the key.
 
 tags:
   - Spaces Keys
@@ -23,6 +24,9 @@ responses:
   '200':
     $ref: 'responses/key_update.yml'
 
+  '400':
+    $ref: 'responses/bad_request.yml'
+
   '401':
     $ref: '../../shared/responses/unauthorized.yml'
 

specification/resources/spaces/key_update.yml

@@ -3,7 +3,8 @@ operationId: spacesKey_update
 summary: "[Beta] Update Spaces Access Keys"
 
 description: |
-  To update Spaces Access Key, send a PUT or PATCH request to `/v2/spaces/keys/$ACCESS_KEY`.
+  To update Spaces Access Key, send a PUT or PATCH request to `/v2/spaces/keys/$ACCESS_KEY`. At the moment, you cannot convert a
+  fullaccess key to a scoped key or vice versa. You can only update the name of the key.
 
 tags:
   - Spaces Keys
@@ -23,6 +24,9 @@ responses:
   '200':
     $ref: 'responses/key_update.yml'
 
+  '400':
+    $ref: 'responses/bad_request.yml'
+
   '401':
     $ref: '../../shared/responses/unauthorized.yml'
 

specification/resources/spaces/models/key.yml

@@ -3,19 +3,19 @@ type: object
 properties:
   name:
     type: string
-    description: The name of your access key.
+    description: The access key's name.
     example: "my-access-key"
 
   grants:
     type: array
-    description: The grants set to this access key.
+    description: The list of permissions for the access key.
     items:
       $ref: 'grant.yml'
     default: []
 
   access_key:
     type: string
-    description: The access key.
+    description: An encrypted string used to access a bucket. 
     example: DOACCESSKEYEXAMPLE
     readOnly: true
 

specification/resources/spaces/models/key_create_response.yml

@@ -3,7 +3,7 @@ allOf:
     properties:
       secret_key:
         type: string
-        description: The secret key. This is the only time the secret key will be returned.
+        description: The secret key used to access the bucket. We return secret keys only once upon creation. Make sure to copy the key and securely store it.
         example: DOSECRETKEYEXAMPLE
         readOnly: true
 

specification/resources/spaces/parameters.yml

@@ -1,7 +1,7 @@
 access_key_name:
   in: path
   name: access_key
-  description: The name of your access key.
+  description: The access key's name.
   required: true
   schema:
     type: string
@@ -21,7 +21,7 @@ sort_direction:
   in: query
   name: sort_direction
   required: false
-  description: The direction to sort by.
+  description: The direction to sort by. Possible values are `asc` or `desc`.
   schema:
     type: string
     default: "desc"
@@ -31,7 +31,7 @@ name:
   in: query
   name: name
   required: false
-  description: The name of the access key.
+  description: The access key's name.
   schema:
     type: string
   example: my-access-key
@@ -40,7 +40,7 @@ bucket:
   in: query
   name: bucket
   required: false
-  description: The name of the bucket.
+  description: The bucket's name.
   schema:
     type: string
   example: my-bucket

specification/resources/spaces/responses/bad_request.yml

@@ -0,0 +1,17 @@
+description: Cannot mix fullaccess permission with scoped permissions
+
+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'
+
+content:
+  application/json:
+    schema:
+      $ref: '../../../shared/models/error.yml'
+    example:
+      id: bad_request
+      message: cannot mix fullaccess permission with scoped permissions.

specification/resources/spaces/responses/key_create.yml

@@ -1,5 +1,5 @@
 description: >-
-  The response will be a JSON object
+  A JSON response containing details about the new key.
 
 headers:
   ratelimit-limit:

specification/resources/spaces/responses/key_list.yml

@@ -1,5 +1,5 @@
 description: >-
-  The result will be a JSON object with a `keys` key.
+  A JSON response containing a list of keys.
 
 headers:
   ratelimit-limit: