Add breadcrumb info to GraphQL categories topic

guides/v2.3/graphql/index.md

@@ -52,3 +52,7 @@ GraphiQL is an in-browser tool for writing, validating, and testing GraphQL quer
 ![GraphiQL browser]({{ page.baseurl }}/graphql/images/graphql-browser.png)
 
 To begin using GraphiQL, set the GraphQL endpoint by entering `http://<magento2-3-server>/graphql` in the URL bar, then click **Set endpoint**. You can use the browser in the right column to determine how to set up a query. Additional examples are also available at [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html).
+
+
+{:.bs-callout .bs-callout-info}
+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

@@ -3,11 +3,11 @@ group: graphql
 title: category endpoint
 ---
 
-The `category` endpoint allows you to search for a single category definition or the entire category tree.
+The `category` endpoint allows you to search for a single category definition or the entire category tree. To return multiple category levels in a single call, define the response so that it contains up to ten nested `children` options. You cannot return the entire category tree if it contains more than 10 sublevels.
 
 ## Query structure
 
-``` json
+```
 category (
    id: int
 ): CategoryTree
@@ -39,17 +39,19 @@ 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
-`children` | `CategoryTree` |
+`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.
+
+
+#### CategoryProducts object
 
 The `products` attribute can contain the following attributes:
 
 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.
-
-#### CategoryProducts
+`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:
 
@@ -60,28 +62,29 @@ Attribute | Data type | Description
 `total_count` | Int | The number of products returned
 
 
-The response can contain up to ten nested `children` options that allow you to return multiple levels of the category tree. In most cases, the entire category tree can be returned in a single call. The following response definition returns two levels of categories:
+#### Breadcrumb object
 
-{% highlight json %}
-{
-  category_tree {
-    id
-    level
-    name
-    children {
-      id
-      level
-      name
-    }
-  }
-}
-{% endhighlight %}
+A breadcrumb trail is a set of links that shows customers where they are in relation to other pages in the
+store.
 
-## Sample Query
+Attribute | Data type | Description
+--- | --- | ---
+`category_id` | Int | An ID that uniquely identifies the category
+`category_name` | String |  The display name of the category
+`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.
 
-{% highlight json %}
+**Request**
+
+```
 {
   category(id: 20) {
     products {
@@ -118,4 +121,131 @@ The following query returns information about category ID `20` and four levels o
       }
   }
 }
-{% endhighlight %}
+```
+**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 (
+   id: 25
+) {
+    id
+    level
+    name
+    breadcrumbs {
+      category_id
+      category_name
+      category_level
+      category_url_key
+    }
+  }
+}
+```
+
+**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"
+        }
+      ]
+    }
+  }
+}
+```