docs: add url, diagram for 3 relations for inclusion

docs/site/BelongsTo-relation.md

@@ -328,6 +328,14 @@ on constructor to avoid "Circular dependency" error (see
 
 ## Querying related models
 
+Different from LB3, LB4 creates a different inclusion resolver for each relation
+type to query related models. Each **relation** has its own inclusion resolver
+`inclusionResolver`. And each **repository** has a built-in property
+`inclusionResolvers` as a registry for its inclusionResolvers. Here is a diagram
+to show the idea:
+
+![inclusion](./imgs/relation-inclusion.png)
+
 A `belongsTo` relation has an `inclusionResolver` function as a property. It
 fetches target models for the given list of source model instances.
 
@@ -336,12 +344,18 @@ belongs to a `Customer`.
 
 After setting up the relation in the repository class, the inclusion resolver
 allows users to retrieve all orders along with their related customers through
-the following code:
+the following code at the repository level:
 
 ```ts
 orderRepo.find({include: [{relation: 'customer'}]});
 ```
 
+or use APIs with controllers:
+
+```
+GET http://localhost:3000/orders?filter[include][][relation]=customer
+```
+
 ### Enable/disable the inclusion resolvers:
 
 - Base repository classes have a public property `inclusionResolvers`, which
@@ -380,12 +394,21 @@ export class OrderRepository extends DefaultCrudRepository {
 ```
 
 - We can simply include the relation in queries via `find()`, `findOne()`, and
-  `findById()` methods. Example:
+  `findById()` methods. For example, these queries return all orders with their
+  `Customer`:
+
+  if you process data at the repository level:
 
   ```ts
   orderRepository.find({include: [{relation: 'customer'}]});
   ```
 
+  this is the same as the url:
+
+  ```
+  GET http://localhost:3000/orders?filter[include][][relation]=customer
+  ```
+
   which returns:
 
   ```ts
@@ -419,6 +442,10 @@ export class OrderRepository extends DefaultCrudRepository {
   ];
   ```
 
+  Here is a diagram to make this more intuitive:
+
+  ![Graph](./imgs/belongsTo-relation-graph.png)
+
 - You can delete a relation from `inclusionResolvers` to disable the inclusion
   for a certain relation. e.g
   `orderRepository.inclusionResolvers.delete('customer')`

docs/site/HasMany-relation.md

@@ -190,9 +190,9 @@ values for these three fields:
 <table>
   <thead>
     <tr>
-      <th>Field Name</th>
-      <th>Description</th>
-      <th>Default Value</th>
+      <th width="95">Field Name</th>
+      <th width="260">Description</th>
+      <th width="260">Default Value</th>
       <th>Example</th>
     </tr>
   </thead>
@@ -421,6 +421,14 @@ issue](https://github.com/strongloop/loopback-next/issues/1179) to follow the di
 
 ## Querying related models
 
+Different from LB3, LB4 creates a different inclusion resolver for each relation
+type to query related models. Each **relation** has its own inclusion resolver
+`inclusionResolver`. And each **repository** has a built-in property
+`inclusionResolvers` as a registry for its inclusionResolvers. Here is a diagram
+to show the idea:
+
+![inclusion](./imgs/relation-inclusion.png)
+
 A `hasMany` relation has an `inclusionResolver` function as a property. It
 fetches target models for the given list of source model instances.
 
@@ -429,12 +437,18 @@ many `Order`s.
 
 After setting up the relation in the repository class, the inclusion resolver
 allows users to retrieve all customers along with their related orders through
-the following code:
+the following code at the repository level:
 
 ```ts
 customerRepo.find({include: [{relation: 'orders'}]});
 ```
 
+or use APIs with controllers:
+
+```
+GET http://localhost:3000/customers?filter[include][][relation]=orders
+```
+
 ### Enable/disable the inclusion resolvers:
 
 - Base repository classes have a public property `inclusionResolvers`, which
@@ -472,12 +486,21 @@ export class CustomerRepository extends DefaultCrudRepository {
 ```
 
 - We can simply include the relation in queries via `find()`, `findOne()`, and
-  `findById()` methods. Example:
+  `findById()` methods. For example, these queries return all customers with
+  their `Order`s:
+
+  if you process data at the repository level:
 
   ```ts
   customerRepository.find({include: [{relation: 'orders'}]});
   ```
 
+  this is the same as the url:
+
+  ```
+  GET http://localhost:3000/customers?filter[include][][relation]=orders
+  ```
+
   which returns:
 
   ```ts
@@ -498,6 +521,10 @@ export class CustomerRepository extends DefaultCrudRepository {
   ];
   ```
 
+  Here is a diagram to make this more intuitive:
+
+  ![Graph](./imgs/hasMany-relation-graph.png)
+
 - You can delete a relation from `inclusionResolvers` to disable the inclusion
   for a certain relation. e.g
   `customerRepository.inclusionResolvers.delete('orders')`

docs/site/hasOne-relation.md

@@ -138,9 +138,9 @@ values for these three fields:
 <table>
   <thead>
     <tr>
-      <th>Field Name</th>
-      <th>Description</th>
-      <th>Default Value</th>
+      <th width="95">Field Name</th>
+      <th width="260">Description</th>
+      <th width="260">Default Value</th>
       <th>Example</th>
     </tr>
   </thead>
@@ -371,6 +371,14 @@ issue](https://github.com/strongloop/loopback-next/issues/1179) to follow the di
 
 ## Querying related models
 
+Different from LB3, LB4 creates a different inclusion resolver for each relation
+type to query related models. Each **relation** has its own inclusion resolver
+`inclusionResolver`. And each **repository** has a built-in property
+`inclusionResolvers` as a registry for its inclusionResolvers. Here is a diagram
+to show the idea:
+
+![inclusion](./imgs/relation-inclusion.png)
+
 A `hasOne` relation has an `inclusionResolver` function as a property. It
 fetches target models for the given list of source model instances.
 
@@ -379,12 +387,18 @@ Using the relation between `Supplier` and `Account` we have shown above, a
 
 After setting up the relation in the repository class, the inclusion resolver
 allows users to retrieve all suppliers along with their related account
-instances through the following code:
+instances through the following code at the repository level:
 
 ```ts
 supplierRepository.find({include: [{relation: 'account'}]});
 ```
 
+or use APIs with controllers:
+
+```
+GET http://localhost:3000/suppliers?filter[include][][relation]=account
+```
+
 ### Enable/disable the inclusion resolvers:
 
 - Base repository classes have a public property `inclusionResolvers`, which
@@ -419,12 +433,21 @@ export class SupplierRepository extends DefaultCrudRepository {
 ```
 
 - We can simply include the relation in queries via `find()`, `findOne()`, and
-  `findById()` methods. Example:
+  `findById()` methods. For example, these queries return all suppliers with
+  their `Account`:
+
+  if you process data at the repository level:
 
   ```ts
   supplierRepository.find({include: [{relation: 'account'}]});
   ```
 
+  this is the same as the url:
+
+  ```
+  GET http://localhost:3000/suppliers?filter[include][][relation]=account
+  ```
+
   which returns:
 
   ```ts
@@ -442,6 +465,10 @@ export class SupplierRepository extends DefaultCrudRepository {
   ];
   ```
 
+  Here is a diagram to make this more intuitive:
+
+  ![Graph](./imgs/hasOne-relation-graph.png)
+
 - You can delete a relation from `inclusionResolvers` to disable the inclusion
   for a certain relation. e.g
   `supplierRepository.inclusionResolvers.delete('account')`