feat(API): improve get /projects/{project_id}/documents documentation

doc/compiled.json

@@ -5569,7 +5569,7 @@
     "/projects/{project_id}/documents": {
       "get": {
         "summary": "List documents",
-        "description": "List all documents the current user has access to.",
+        "description": "Returns all documents in a project that the authenticated user has read access to. A Document is a source file — such as an HTML or YAML file — that has been uploaded to Phrase Strings and whose content is segmented into translation keys for localization.\n\nUse this endpoint to enumerate documents before downloading, previewing, or triggering translation workflows for individual files.\n\nThe q parameter performs a prefix match on the document name (case-insensitive). For example, passing q=invoice returns documents whose names begin with \"invoice\" but not documents containing \"invoice\" elsewhere in the name.\n\nRequires the read OAuth scope. Returns 403 when the requesting user does not have read permission on documents in this project.\n",
         "operationId": "documents/list",
         "tags": [
           "Documents"
@@ -5579,19 +5579,20 @@
             "$ref": "#/components/parameters/X-PhraseApp-OTP"
           },
           {
-            "$ref": "#/components/parameters/page"
+            "$ref": "#/components/parameters/project_id"
           },
           {
-            "$ref": "#/components/parameters/per_page"
+            "$ref": "#/components/parameters/page"
           },
           {
-            "$ref": "#/components/parameters/project_id"
+            "$ref": "#/components/parameters/per_page"
           },
           {
-            "description": "Search query. Filters documents by name (case-insensitive substring match).",
+            "description": "Filter documents by name prefix. Returns documents whose name starts with the given value (case-insensitive).",
+            "example": "invoice",
             "name": "q",
             "in": "query",
-            "example": "invoice",
+            "required": false,
             "schema": {
               "type": "string"
             }
@@ -5630,6 +5631,25 @@
                       "updated_at": "2015-01-28T09:52:53Z"
                     }
                   }
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Example document list response",
+                    "value": [
+                      {
+                        "id": "abcd1234cdef1234abcd1234cdef1234",
+                        "name": "email.html",
+                        "created_at": "2015-01-28T09:52:53Z",
+                        "updated_at": "2015-03-04T11:22:30Z"
+                      },
+                      {
+                        "id": "ef012345ef012345ef012345ef012345",
+                        "name": "invoice.yaml",
+                        "created_at": "2015-02-10T14:30:00Z",
+                        "updated_at": "2015-03-01T08:00:00Z"
+                      }
+                    ]
+                  }
                 }
               }
             },
@@ -5659,7 +5679,7 @@
           },
           "403": {
             "$ref": "#/components/responses/403",
-            "description": "Forbidden. Returned when the access token lacks the `read` scope or when the requesting user is not allowed to list documents in this project."
+            "description": "Forbidden. Returned when the access token lacks the `read` OAuth scope, when the account email is unconfirmed, or when the requesting user does not have read permission on documents in this project."
           },
           "404": {
             "$ref": "#/components/responses/404"
@@ -5671,7 +5691,11 @@
         "x-code-samples": [
           {
             "lang": "Curl",
-            "source": "curl \"https://api.phrase.com/v2/documents?project_id=asdf\" \\\n  -u USERNAME_OR_ACCESS_TOKEN"
+            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/documents\" \\\n  -u USERNAME_OR_ACCESS_TOKEN"
+          },
+          {
+            "lang": "Response",
+            "source": "[\n  {\n    \"id\": \"abcd1234cdef1234abcd1234cdef1234\",\n    \"name\": \"email.html\",\n    \"created_at\": \"2015-01-28T09:52:53Z\",\n    \"updated_at\": \"2015-03-04T11:22:30Z\"\n  },\n  {\n    \"id\": \"ef012345ef012345ef012345ef012345\",\n    \"name\": \"invoice.yaml\",\n    \"created_at\": \"2015-02-10T14:30:00Z\",\n    \"updated_at\": \"2015-03-01T08:00:00Z\"\n  }\n]"
           },
           {
             "lang": "CLI v2",

paths/documents/index.yaml

@@ -1,19 +1,26 @@
 ---
 summary: List documents
-description: List all documents the current user has access to.
+description: |
+  Returns all documents in a project that the authenticated user has read access to. A Document is a source file — such as an HTML or YAML file — that has been uploaded to Phrase Strings and whose content is segmented into translation keys for localization.
+
+  Use this endpoint to enumerate documents before downloading, previewing, or triggering translation workflows for individual files.
+
+  The q parameter performs a prefix match on the document name (case-insensitive). For example, passing q=invoice returns documents whose names begin with "invoice" but not documents containing "invoice" elsewhere in the name.
+
+  Requires the read OAuth scope. Returns 403 when the requesting user does not have read permission on documents in this project.
 operationId: documents/list
 tags:
 - Documents
 parameters:
 - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+- "$ref": "../../parameters.yaml#/project_id"
 - "$ref": "../../parameters.yaml#/page"
 - "$ref": "../../parameters.yaml#/per_page"
-- "$ref": "../../parameters.yaml#/project_id"
-- description: |-
-    Search query. Filters documents by name (case-insensitive substring match).
+- description: Filter documents by name prefix. Returns documents whose name starts with the given value (case-insensitive).
+  example: invoice
   name: q
   in: query
-  example: invoice
+  required: false
   schema:
     type: string
 responses:
@@ -25,6 +32,18 @@ responses:
           type: array
           items:
             "$ref": "../../schemas/document.yaml#/document"
+        examples:
+          success:
+            summary: Example document list response
+            value:
+              - id: abcd1234cdef1234abcd1234cdef1234
+                name: email.html
+                created_at: '2015-01-28T09:52:53Z'
+                updated_at: '2015-03-04T11:22:30Z'
+              - id: ef012345ef012345ef012345ef012345
+                name: invoice.yaml
+                created_at: '2015-02-10T14:30:00Z'
+                updated_at: '2015-03-01T08:00:00Z'
     headers:
       X-Rate-Limit-Limit:
         "$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
@@ -44,14 +63,30 @@ responses:
     "$ref": "../../responses.yaml#/401"
   '403':
     "$ref": "../../responses.yaml#/403"
-    description: Forbidden. Returned when the access token lacks the `read` scope or when the requesting user is not allowed to list documents in this project.
+    description: Forbidden. Returned when the access token lacks the `read` OAuth scope, when the account email is unconfirmed, or when the requesting user does not have read permission on documents in this project.
   '429':
     "$ref": "../../responses.yaml#/429"
 x-code-samples:
 - lang: Curl
   source: |-
-    curl "https://api.phrase.com/v2/documents?project_id=asdf" \
+    curl "https://api.phrase.com/v2/projects/:project_id/documents" \
       -u USERNAME_OR_ACCESS_TOKEN
+- lang: Response
+  source: |-
+    [
+      {
+        "id": "abcd1234cdef1234abcd1234cdef1234",
+        "name": "email.html",
+        "created_at": "2015-01-28T09:52:53Z",
+        "updated_at": "2015-03-04T11:22:30Z"
+      },
+      {
+        "id": "ef012345ef012345ef012345ef012345",
+        "name": "invoice.yaml",
+        "created_at": "2015-02-10T14:30:00Z",
+        "updated_at": "2015-03-01T08:00:00Z"
+      }
+    ]
 - lang: CLI v2
   source: |-
     phrase documents list \