From 515709062544866689d03f306abd503223baf6df Mon Sep 17 00:00:00 2001 From: Junior Dev Agent <288084488+junior-ai-bot[bot]@users.noreply.github.com> Date: Fri, 18 Sep 2026 06:32:04 +0000 Subject: [PATCH 1/2] STRINGS-3481 - document GET /languages in the published OpenAPI spec The API-wide GET /languages endpoint (Api::V2::LanguagesController#index in strings-app) exists and works but was missing from the spec source and published doc/compiled.json, making it undiscoverable via the API reference. Add the path, a "languages" schema modeling the real response shape (an object mapping locale/language code to display name, verified against the live https://api.phrase.com/v2/languages response), and the "Languages" tag, then regenerate doc/compiled.json via `make bundle`. Co-Authored-By: Claude Sonnet 5 --- doc/compiled.json | 67 ++++++++++++++++++++++++++++++++++++++ main.yaml | 1 + paths.yaml | 3 ++ paths/languages/index.yaml | 36 ++++++++++++++++++++ schemas.yaml | 2 ++ schemas/language.yaml | 14 ++++++++ 6 files changed, 123 insertions(+) create mode 100644 paths/languages/index.yaml create mode 100644 schemas/language.yaml diff --git a/doc/compiled.json b/doc/compiled.json index f1d1d0f3d..1745898c0 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -125,6 +125,9 @@ { "name": "Keys" }, + { + "name": "Languages" + }, { "name": "Linked Keys" }, @@ -2278,6 +2281,19 @@ "includes_locale_information": false } }, + "languages": { + "type": "object", + "title": "languages", + "description": "Map of all languages supported by Phrase Strings, keyed by their language/locale code. Each value is the human-readable display name for that code.", + "additionalProperties": { + "type": "string" + }, + "example": { + "de": "German", + "en": "English", + "fr": "French" + } + }, "project": { "type": "object", "title": "project", @@ -6249,6 +6265,57 @@ "x-cli-version": "2.5" } }, + "/languages": { + "get": { + "summary": "List languages", + "description": "Returns all languages/locale codes that Phrase Strings recognizes, mapped to their\nhuman-readable display name. This endpoint does not require authentication and is\nnot subject to rate limiting.\n", + "operationId": "languages/list", + "tags": [ + "Languages" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/languages" + }, + "examples": { + "default": { + "value": { + "de": "German", + "en": "English", + "fr": "French" + } + } + } + } + }, + "headers": { + "X-Rate-Limit-Limit": { + "$ref": "#/components/headers/X-Rate-Limit-Limit" + }, + "X-Rate-Limit-Remaining": { + "$ref": "#/components/headers/X-Rate-Limit-Remaining" + }, + "X-Rate-Limit-Reset": { + "$ref": "#/components/headers/X-Rate-Limit-Reset" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + } + }, + "x-code-samples": [ + { + "lang": "Curl", + "source": "curl \"https://api.phrase.com/v2/languages\" \\\n -u USERNAME_OR_ACCESS_TOKEN" + } + ] + } + }, "/projects/{project_id}/documents": { "get": { "summary": "List documents", diff --git a/main.yaml b/main.yaml index 4d14c27b0..23e9149c5 100644 --- a/main.yaml +++ b/main.yaml @@ -170,6 +170,7 @@ tags: - name: Jobs - name: Key Format Annotations - name: Keys + - name: Languages - name: Linked Keys - name: Locales - name: Locale Downloads diff --git a/paths.yaml b/paths.yaml index e480dfa3a..fecaffde8 100644 --- a/paths.yaml +++ b/paths.yaml @@ -4,6 +4,9 @@ "/formats": get: "$ref": "./paths/formats/index.yaml" +"/languages": + get: + "$ref": "./paths/languages/index.yaml" "/projects/{project_id}/documents": get: "$ref": "./paths/documents/index.yaml" diff --git a/paths/languages/index.yaml b/paths/languages/index.yaml new file mode 100644 index 000000000..5c33a9a54 --- /dev/null +++ b/paths/languages/index.yaml @@ -0,0 +1,36 @@ +--- +summary: List languages +description: | + Returns all languages/locale codes that Phrase Strings recognizes, mapped to their + human-readable display name. This endpoint does not require authentication and is + not subject to rate limiting. +operationId: languages/list +tags: +- Languages +responses: + '200': + description: OK + content: + application/json: + schema: + "$ref": "../../schemas/language.yaml#/languages" + examples: + default: + value: + de: German + en: English + fr: French + headers: + X-Rate-Limit-Limit: + "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" + X-Rate-Limit-Remaining: + "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" + X-Rate-Limit-Reset: + "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + '400': + "$ref": "../../responses.yaml#/400" +x-code-samples: +- lang: Curl + source: |- + curl "https://api.phrase.com/v2/languages" \ + -u USERNAME_OR_ACCESS_TOKEN diff --git a/schemas.yaml b/schemas.yaml index 79e5a306a..10dd2a2bb 100644 --- a/schemas.yaml +++ b/schemas.yaml @@ -72,6 +72,8 @@ schemas: "$ref": schemas/upload.yaml#/upload format: "$ref": schemas/format.yaml#/format + languages: + "$ref": schemas/language.yaml#/languages project: "$ref": schemas/project.yaml#/project project_details: diff --git a/schemas/language.yaml b/schemas/language.yaml new file mode 100644 index 000000000..5b988c7ad --- /dev/null +++ b/schemas/language.yaml @@ -0,0 +1,14 @@ +--- +languages: + type: object + title: languages + description: >- + Map of all languages supported by Phrase Strings, keyed by their + language/locale code. Each value is the human-readable display name + for that code. + additionalProperties: + type: string + example: + de: German + en: English + fr: French From 0193c64437ddfa9fcb1cfe73030463ec15398b1c Mon Sep 17 00:00:00 2001 From: Junior Dev Agent <288084488+junior-ai-bot[bot]@users.noreply.github.com> Date: Fri, 18 Sep 2026 06:42:13 +0000 Subject: [PATCH 2/2] fix: address review feedback on /languages endpoint - Rename tag from "Languages" to "Supported Languages" per reviewer request - Rename summary to "List supported languages" - Remove rate-limiting note from description (may change in the future) Co-Authored-By: Junior (Claude Sonnet 5) --- doc/compiled.json | 12 ++++++------ main.yaml | 2 +- paths/languages/index.yaml | 7 +++---- 3 files changed, 10 insertions(+), 11 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 1745898c0..5c7e54889 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -125,9 +125,6 @@ { "name": "Keys" }, - { - "name": "Languages" - }, { "name": "Linked Keys" }, @@ -200,6 +197,9 @@ { "name": "Style guides" }, + { + "name": "Supported Languages" + }, { "name": "Tags" }, @@ -6267,11 +6267,11 @@ }, "/languages": { "get": { - "summary": "List languages", - "description": "Returns all languages/locale codes that Phrase Strings recognizes, mapped to their\nhuman-readable display name. This endpoint does not require authentication and is\nnot subject to rate limiting.\n", + "summary": "List supported languages", + "description": "Returns all languages/locale codes that Phrase Strings recognizes, mapped to their\nhuman-readable display name. This endpoint does not require authentication.\n", "operationId": "languages/list", "tags": [ - "Languages" + "Supported Languages" ], "responses": { "200": { diff --git a/main.yaml b/main.yaml index 23e9149c5..7cf82728c 100644 --- a/main.yaml +++ b/main.yaml @@ -170,7 +170,6 @@ tags: - name: Jobs - name: Key Format Annotations - name: Keys - - name: Languages - name: Linked Keys - name: Locales - name: Locale Downloads @@ -248,6 +247,7 @@ tags: - name: Screenshots - name: Spaces - name: Style guides + - name: Supported Languages - name: Tags - name: Teams - name: Translations diff --git a/paths/languages/index.yaml b/paths/languages/index.yaml index 5c33a9a54..ac2433c55 100644 --- a/paths/languages/index.yaml +++ b/paths/languages/index.yaml @@ -1,12 +1,11 @@ --- -summary: List languages +summary: List supported languages description: | Returns all languages/locale codes that Phrase Strings recognizes, mapped to their - human-readable display name. This endpoint does not require authentication and is - not subject to rate limiting. + human-readable display name. This endpoint does not require authentication. operationId: languages/list tags: -- Languages +- Supported Languages responses: '200': description: OK