fix(API): improve get /projects/{project_id}/keys/{id}/key_links documentation

doc/compiled.json

@@ -4808,6 +4808,66 @@
             },
             "description": "The child translation keys linked to the parent."
           }
+        },
+        "example": {
+          "created_at": "2024-03-15T10:22:00Z",
+          "updated_at": "2024-03-15T10:22:00Z",
+          "created_by": {
+            "id": "usr1a2b3c4d5e6f7a8b9c",
+            "username": "jane.doe",
+            "name": "Jane Doe",
+            "gravatar_uid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
+          },
+          "updated_by": {
+            "id": "usr1a2b3c4d5e6f7a8b9c",
+            "username": "jane.doe",
+            "name": "Jane Doe",
+            "gravatar_uid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
+          },
+          "account": {
+            "id": "acct9z8y7x6w5v4u3t2s",
+            "name": "Acme Translations",
+            "slug": "acme-translations",
+            "company": "Acme Corp",
+            "created_at": "2023-01-10T08:00:00Z",
+            "updated_at": "2023-06-01T12:00:00Z",
+            "company_logo_url": "https://example.com/logos/acme.png"
+          },
+          "parent": {
+            "id": "ijkl9012mnop3456ijkl9012",
+            "name": "home.hero.title",
+            "plural": false,
+            "use_ordinal_rules": false,
+            "data_type": "string",
+            "tags": [
+              "ui",
+              "homepage"
+            ]
+          },
+          "children": [
+            {
+              "id": "ijkl9012mnop3456ijkl9012mnop3456",
+              "name": "home.hero.title_short",
+              "plural": false,
+              "use_ordinal_rules": false,
+              "data_type": "string",
+              "tags": [
+                "ui",
+                "homepage"
+              ]
+            },
+            {
+              "id": "abcd1234efgh5678abcd1234efgh5678",
+              "name": "home.hero.title_long",
+              "plural": false,
+              "use_ordinal_rules": false,
+              "data_type": "string",
+              "tags": [
+                "ui",
+                "homepage"
+              ]
+            }
+          ]
         }
       },
       "repo_sync": {
@@ -31170,7 +31230,7 @@
       },
       "get": {
         "summary": "List child keys of a parent key",
-        "description": "Returns detailed information about a parent key, including its linked child keys.",
+        "description": "Returns the key link record for a parent key, including all child keys associated with it. Key linking lets translation keys share translations — a child key inherits content from its designated parent. Use this endpoint to inspect which keys are linked under a given parent before unlinking them or auditing translation consistency across related keys.\n\nThe key identified by `id` must be designated as a parent key (it must have at least one child key linked to it). Listing the links of a key that is not a parent returns 400.\n",
         "operationId": "key_links/index",
         "tags": [
           "Linked Keys"
@@ -31198,29 +31258,13 @@
             }
           },
           "400": {
-            "description": "Bad Request",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "message": {
-                      "type": "string"
-                    }
-                  },
-                  "example": {
-                    "message": "Key <parent_key_code> is not a parent key"
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/responses/400"
           },
           "401": {
             "$ref": "#/components/responses/401"
           },
           "403": {
-            "$ref": "#/components/responses/403",
-            "description": "Forbidden. Returned when the access token lacks the `write` scope or when the requesting user is not allowed to read key links for this key."
+            "$ref": "#/components/responses/403"
           },
           "404": {
             "$ref": "#/components/responses/404"

paths/key_links/index.yaml

@@ -1,6 +1,9 @@
 ---
 summary: List child keys of a parent key
-description: Returns detailed information about a parent key, including its linked child keys.
+description: |
+  Returns the key link record for a parent key, including all child keys associated with it. Key linking lets translation keys share translations — a child key inherits content from its designated parent. Use this endpoint to inspect which keys are linked under a given parent before unlinking them or auditing translation consistency across related keys.
+
+  The key identified by `id` must be designated as a parent key (it must have at least one child key linked to it). Listing the links of a key that is not a parent returns 400.
 operationId: key_links/index
 tags:
 - Linked Keys
@@ -16,21 +19,11 @@ responses:
         schema:
           $ref: "../../schemas/key_link.yaml#/key_link"
   '400':
-    description: Bad Request
-    content:
-      application/json:
-        schema:
-          type: object
-          properties:
-            message:
-              type: string
-          example:
-            message: "Key <parent_key_code> is not a parent key"
+    "$ref": "../../responses.yaml#/400"
   '401':
     "$ref": "../../responses.yaml#/401"
   '403':
     "$ref": "../../responses.yaml#/403"
-    description: Forbidden. Returned when the access token lacks the `write` scope or when the requesting user is not allowed to read key links for this key.
   '404':
     "$ref": "../../responses.yaml#/404"
   '429':

schemas/key_link.yaml

@@ -26,3 +26,44 @@ key_link:
       items:
         $ref: "./key_preview.yaml#/key_preview"
       description: The child translation keys linked to the parent.
+  example:
+    created_at: "2024-03-15T10:22:00Z"
+    updated_at: "2024-03-15T10:22:00Z"
+    created_by:
+      id: "usr1a2b3c4d5e6f7a8b9c"
+      username: "jane.doe"
+      name: "Jane Doe"
+      gravatar_uid: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
+    updated_by:
+      id: "usr1a2b3c4d5e6f7a8b9c"
+      username: "jane.doe"
+      name: "Jane Doe"
+      gravatar_uid: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
+    account:
+      id: "acct9z8y7x6w5v4u3t2s"
+      name: "Acme Translations"
+      slug: "acme-translations"
+      company: "Acme Corp"
+      created_at: "2023-01-10T08:00:00Z"
+      updated_at: "2023-06-01T12:00:00Z"
+      company_logo_url: "https://example.com/logos/acme.png"
+    parent:
+      id: "ijkl9012mnop3456ijkl9012"
+      name: "home.hero.title"
+      plural: false
+      use_ordinal_rules: false
+      data_type: "string"
+      tags: ["ui", "homepage"]
+    children:
+      - id: "ijkl9012mnop3456ijkl9012mnop3456"
+        name: "home.hero.title_short"
+        plural: false
+        use_ordinal_rules: false
+        data_type: "string"
+        tags: ["ui", "homepage"]
+      - id: "abcd1234efgh5678abcd1234efgh5678"
+        name: "home.hero.title_long"
+        plural: false
+        use_ordinal_rules: false
+        data_type: "string"
+        tags: ["ui", "homepage"]