editorial comments

guides/v2.3/graphql/index.md

@@ -55,4 +55,4 @@ To begin using GraphiQL, set the GraphQL endpoint by entering `http://<magento2-
 
 
 {:.bs-callout .bs-callout-info}
-You can access the GraphQL introspection feature only if your Magento instance is in developer mode. See [Set the Magento mode]({{ page.baseurl }}/config-guide/cli/config-cli-subcommands-mode.html) for more information about modes.
+You can access the GraphQL introspection feature only if your Magento instance is in developer mode. [Set the Magento mode]({{ page.baseurl }}/config-guide/cli/config-cli-subcommands-mode.html) describes how to check and change the mode.

guides/v2.3/graphql/reference/categories.md

@@ -7,7 +7,7 @@ The `category` endpoint allows you to search for a single category definition or
 
 ## Query structure
 
-``` 
+```
 category (
    id: int
 ): CategoryTree
@@ -39,7 +39,7 @@ Attribute | Data type | Description
 `product_count`| Int | The number of products in the category
 `default_sort_by`| String | The attribute to use for sorting
 `products(<attributes>)` | `CategoryProducts` | The list of products assigned to the category
-`breadcrumbs` | `Breadcrumb` |
+`breadcrumbs` | `Breadcrumb` | A `Breadcrumb` object contains information about each category that
 `children` | `CategoryTree` | A `CategoryTree` object that contains information about a child category. You can specify up to 10 levels of child categories.
 
 
@@ -51,7 +51,7 @@ Attribute | Data type | Description
 --- | --- | ---
 `pageSize` | Int | Specifies the maximum number of results to return at once. This attribute is optional. The default value is 20.
 `currentPage` | Int |  Specifies which page of results to return. The default value is 1.
-`sort` | `ProductSortInput` | Specifies which attribute to sort on, and whether to return the results in ascending or descending order. See [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) for more information.
+`sort` | `ProductSortInput` | Specifies which attribute to sort on, and whether to return the results in ascending or descending order. [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) describes sort orders.
 
 The `CategoryProducts` object contains the following attributes:
 
@@ -74,11 +74,16 @@ Attribute | Data type | Description
 `category_level` | Int | Indicates the depth of the category within the tree
 `category_url_key` | String | The url key assigned to the category
 
+#### CategoryTree object
+
+This `CategoryTree` object contains information about the next level of subcategories of the category specified in the original query.
 
 ## Sample Queries
 
 The following query returns information about category ID `20` and four levels of subcategories. In the sample data, category ID `20` is assigned to the "Women" category.
 
+**Request**
+
 ```
 {
   category(id: 20) {
@@ -117,9 +122,88 @@ The following query returns information about category ID `20` and four levels o
   }
 }
 ```
+**Response**
+
+``` json
+{
+  "data": {
+    "category": {
+      "products": {
+        "total_count": 0,
+        "page_info": {
+          "current_page": 1,
+          "page_size": 20
+        }
+      },
+      "children_count": "8",
+      "children": [
+        {
+          "id": 21,
+          "level": 3,
+          "name": "Tops",
+          "path": "1/2/20/21",
+          "children": []
+        },
+        {
+          "id": 22,
+          "level": 3,
+          "name": "Bottoms",
+          "path": "1/2/20/22",
+          "children": [
+            {
+              "id": 23,
+              "level": 4,
+              "name": "Jackets",
+              "path": "1/2/20/21/23",
+              "children": []
+            },
+            {
+              "id": 24,
+              "level": 4,
+              "name": "Hoodies & Sweatshirts",
+              "path": "1/2/20/21/24",
+              "children": []
+            },
+            {
+              "id": 25,
+              "level": 4,
+              "name": "Tees",
+              "path": "1/2/20/21/25",
+              "children": []
+            },
+            {
+              "id": 26,
+              "level": 4,
+              "name": "Bras & Tanks",
+              "path": "1/2/20/21/26",
+              "children": []
+            },
+            {
+              "id": 27,
+              "level": 4,
+              "name": "Pants",
+              "path": "1/2/20/22/27",
+              "children": []
+            },
+            {
+              "id": 28,
+              "level": 4,
+              "name": "Shorts",
+              "path": "1/2/20/22/28",
+              "children": []
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
 
 The following query returns breadcrumb information about the women's tops category (`id` = 25).
 
+**Request**
+
 ```
 {
   category (
@@ -137,3 +221,31 @@ The following query returns breadcrumb information about the women's tops catego
   }
 }
 ```
+
+**Response**
+
+``` json
+{
+  "data": {
+    "category": {
+      "id": 25,
+      "level": 4,
+      "name": "Tees",
+      "breadcrumbs": [
+        {
+          "category_id": 20,
+          "category_name": "Women",
+          "category_level": 2,
+          "category_url_key": "women"
+        },
+        {
+          "category_id": 21,
+          "category_name": "Tops",
+          "category_level": 3,
+          "category_url_key": "tops-women"
+        }
+      ]
+    }
+  }
+}
+```