From edd317fe66ee236e518cf6c53e8a0224a55c19fc Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:53:41 +0200 Subject: [PATCH 1/3] feat(API): improve get /projects/{project_id}/documents documentation --- doc/compiled.json | 40 ++++++++++++++++++++++++------- paths/documents/index.yaml | 49 ++++++++++++++++++++++++++++++++------ 2 files changed, 74 insertions(+), 15 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index afba5090..f67214b7 100644 --- a/doc/compiled.json +++ b/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", diff --git a/paths/documents/index.yaml b/paths/documents/index.yaml index 718672f5..aa1b4080 100644 --- a/paths/documents/index.yaml +++ b/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 \ From f916aa048aafb553cb76bd0a24c1ac038c93ed9c Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 21:01:21 +0100 Subject: [PATCH 2/3] docs(API): address review on get /projects/{project_id}/documents - Correct the document-type description: only HTML and DOCX files are listed (was 'HTML or YAML'); fix the example value invoice.yaml -> invoice.docx accordingly. (theSoenke) - Drop the 'Requires the read OAuth scope ...' sentence from the description; no other endpoint documents scopes in prose and the 403 response already explains the read requirement. (theSoenke) - Remove the 'Response' code sample; the 200 example already shows the response shape and no other endpoint inlines a response sample. (theSoenke) Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 8 ++------ paths/documents/index.yaml | 22 ++-------------------- 2 files changed, 4 insertions(+), 26 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index f67214b7..7ae44a6b 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5569,7 +5569,7 @@ "/projects/{project_id}/documents": { "get": { "summary": "List documents", - "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", + "description": "Returns all documents in a project that the authenticated user has read access to. A Document is a source file — an HTML or DOCX 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", "operationId": "documents/list", "tags": [ "Documents" @@ -5644,7 +5644,7 @@ }, { "id": "ef012345ef012345ef012345ef012345", - "name": "invoice.yaml", + "name": "invoice.docx", "created_at": "2015-02-10T14:30:00Z", "updated_at": "2015-03-01T08:00:00Z" } @@ -5693,10 +5693,6 @@ "lang": "Curl", "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", "source": "phrase documents list \\\n--project_id \\\n--access_token " diff --git a/paths/documents/index.yaml b/paths/documents/index.yaml index aa1b4080..8f5442ec 100644 --- a/paths/documents/index.yaml +++ b/paths/documents/index.yaml @@ -1,13 +1,11 @@ --- summary: List documents 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. + Returns all documents in a project that the authenticated user has read access to. A Document is a source file — an HTML or DOCX 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 @@ -41,7 +39,7 @@ responses: created_at: '2015-01-28T09:52:53Z' updated_at: '2015-03-04T11:22:30Z' - id: ef012345ef012345ef012345ef012345 - name: invoice.yaml + name: invoice.docx created_at: '2015-02-10T14:30:00Z' updated_at: '2015-03-01T08:00:00Z' headers: @@ -71,22 +69,6 @@ x-code-samples: source: |- 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 \ From 024ecfc5437652390d38b52bd5645d6cd0b6f999 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 09:06:53 +0200 Subject: [PATCH 3/3] docs(API): move error-response prose to shared responses.yaml Review feedback: error response descriptions should stay in the shared responses.yaml for consistency, not be re-authored inline per operation. Under OpenAPI 3.0 a description sibling of $ref is ignored anyway, so the inline text never rendered. Strip the inline $ref-sibling response descriptions (now bare $refs); the shared response owns the wording. Genuinely custom (non-$ref) response bodies are left intact. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 3 +-- paths/documents/index.yaml | 1 - 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 7ae44a6b..c9a6df68 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5678,8 +5678,7 @@ "$ref": "#/components/responses/401" }, "403": { - "$ref": "#/components/responses/403", - "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." + "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" diff --git a/paths/documents/index.yaml b/paths/documents/index.yaml index 8f5442ec..581543a1 100644 --- a/paths/documents/index.yaml +++ b/paths/documents/index.yaml @@ -61,7 +61,6 @@ responses: "$ref": "../../responses.yaml#/401" '403': "$ref": "../../responses.yaml#/403" - 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: