feat(API): improve POST /projects/{project_id}/screenshots documentation

paths/screenshots/create.yaml

@@ -1,7 +1,37 @@
 ---
 summary: Create a screenshot
-description: Create a new screenshot.
-operationId: screenshot/create
+description: |
+  Uploads a new screenshot image to the specified project, making it available for
+  translators as visual context. Screenshots are image files associated with a project
+  and can subsequently be linked to one or more translation keys via screenshot markers.
+
+  Use this endpoint when you want to provide translators with on-screen context for
+  the strings they are working on. After creating a screenshot, use the screenshot
+  markers endpoint (`POST /projects/{project_id}/screenshots/{screenshot_id}/markers`)
+  to associate the screenshot with specific translation keys.
+
+  The `id` field in the response is the screenshot's string code (not a numeric primary
+  key). Pass this value as the `screenshot_id` path segment in subsequent marker or
+  screenshot calls.
+
+  **File upload:** The request body must be sent as `multipart/form-data`. The `filename`
+  field is required; omitting it or uploading a file that cannot be processed by the
+  image pipeline will return a 422 with an error on the `filename` field.
+
+  **Side effects:** A `screenshots:create` event is dispatched upon success, which may
+  trigger configured webhook notifications for your project.
+
+  **Access control:** The requesting token must carry the `write` OAuth scope, and the
+  authenticated user must have manage permission on the Screenshot resource within the
+  project. Protected projects cannot receive new screenshots regardless of the user's
+  role, returning a 403. Access is also gated on the Attachable Screenshots feature
+  being enabled for the account; a 403 is returned when the feature is unavailable on
+  the account's plan. When the Phrase Sketch Plugin user-agent is detected and the
+  account's Sketch Plugin feature is not enabled, a 403 is also returned.
+
+  **Branches:** Pass the `branch` parameter in the request body to create the screenshot
+  within a specific branch context. Omit it to create against the main branch.
+operationId: screenshots/create
 tags:
 - Screenshots
 parameters:
@@ -14,6 +44,14 @@ responses:
       application/json:
         schema:
           "$ref": "../../schemas/screenshot.yaml#/screenshot"
+        example:
+          id: d2e056aa9e70b01121f41693e344f5ee
+          name: Onboarding step 1
+          description: First step of the user onboarding flow showing the project selection screen
+          screenshot_url: https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png
+          created_at: '2024-03-15T10:22:31Z'
+          updated_at: '2024-03-18T14:05:12Z'
+          markers_count: 0
     headers:
       X-Rate-Limit-Limit:
         "$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
@@ -23,32 +61,42 @@ responses:
         "$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
   '400':
     "$ref": "../../responses.yaml#/400"
-  '404':
-    "$ref": "../../responses.yaml#/404"
   '401':
     "$ref": "../../responses.yaml#/401"
   '403':
     "$ref": "../../responses.yaml#/403"
-    description: Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to create screenshots in this project, or when the account does not have the Attachable Screenshots feature.
+    description: |
+      Forbidden. Returned when:
+      - The access token lacks the `write` OAuth scope, or the user's account is unconfirmed.
+      - The authenticated user does not have manage permission on screenshots in this project.
+      - The project is protected, which prevents creating new screenshots.
+      - The account does not have the Attachable Screenshots feature enabled on its plan.
+      - The request originates from the Phrase Sketch Plugin and the account's Sketch Plugin
+        feature is not enabled.
+  '404':
+    "$ref": "../../responses.yaml#/404"
   '422':
     "$ref": "../../responses.yaml#/422"
   '429':
     "$ref": "../../responses.yaml#/429"
 x-code-samples:
 - lang: Curl
   source: |-
-    curl "https://api.phrase.com/v2/projects/:project_id/screenshots" \
+    curl "https://api.phrase.com/v2/projects/3d7ce831a3e9e1b843dc16d36ee5b9f4/screenshots" \
       -u USERNAME_OR_ACCESS_TOKEN \
       -X POST \
-      -F branch=my-feature-branch \
-      -F name=A%20screenshot%20name \
-      -F description=A%20screenshot%20description \
-      -F filename=@/path/to/my/screenshot.png
+      -F "branch=my-feature-branch" \
+      -F "name=Onboarding step 1" \
+      -F "description=First step of the user onboarding flow" \
+      -F "filename=@/path/to/screenshot.png"
 - lang: CLI v2
   source: |-
     phrase screenshots create \
-    --project_id <project_id> \
-    --branch "my-feature-branch" --name "A screenshot name" --description "A screenshot description" --filename "/path/to/my/screenshot.png" \
+    --project_id 3d7ce831a3e9e1b843dc16d36ee5b9f4 \
+    --branch "my-feature-branch" \
+    --name "Onboarding step 1" \
+    --description "First step of the user onboarding flow" \
+    --filename "/path/to/screenshot.png" \
     --access_token <token>
 requestBody:
   required: true
@@ -57,22 +105,23 @@ requestBody:
       schema:
         type: object
         title: screenshot/create/parameters
+        required:
+        - filename
         properties:
           branch:
-            description: specify the branch to use
+            description: Branch to create the screenshot in. Omit to target the main branch.
             type: string
             example: my-feature-branch
           name:
-            description: Name of the screenshot
+            description: Name of the screenshot shown in the Phrase dashboard and to translators.
             type: string
-            example: A screenshot name
+            example: Onboarding step 1
           description:
-            description: Description of the screenshot
+            description: Optional longer description providing additional context about what the screenshot depicts.
             type: string
-            example: A screenshot description
+            example: First step of the user onboarding flow showing the project selection screen
           filename:
-            description: Screenshot file
+            description: The screenshot image file to upload. Required. If the file cannot be processed, a 422 is returned with an error on the `filename` field.
             type: string
             format: binary
-            example: "/path/to/my/screenshot.png"
 x-cli-version: '2.5'