docs: Add docs on defining graphql types

docs/content/plugins/plugin-examples/defining-db-entity.md

@@ -5,7 +5,7 @@ showtoc: true
 
 # Defining a new database entity
 
-This example shows how new TypeORM database entities can be defined by plugins.
+This example shows how new [TypeORM database entities](https://typeorm.io/entities) can be defined by plugins.
 
 ```TypeScript
 // product-review.entity.ts
@@ -43,3 +43,7 @@ import { ProductReview } from './product-review.entity';
 })
 export class ReviewsPlugin {}
 ```
+
+## Corresponding GraphQL type
+
+Once you have defined a new DB entity, it is likely that you want to expose it in your GraphQL API. Here's how to [define a new type in your GraphQL API]({{< relref "extending-graphql-api" >}}#defining-a-new-type).

docs/content/plugins/plugin-examples/extending-graphql-api.md

@@ -5,6 +5,39 @@ showtoc: true
 
 # Extending the GraphQL API
 
+Extension to the GraphQL API consists of two parts:
+
+1. **Schema extensions**. These define new types, fields, queries and mutations.
+2. **Resolvers**. These provide the logic that backs up the schema extensions.
+
+The Shop API and Admin APIs can be extended independently:
+
+```TypeScript {hl_lines=["16-22"]}
+import { PluginCommonModule, VendurePlugin } from '@vendure/core';
+import gql from 'graphql-tag';
+import { TopSellersResolver } from './top-products.resolver';
+
+const schemaExtension = gql`
+  extend type Query {
+    topProducts: [Product!]!
+  }
+`
+
+@VendurePlugin({
+  imports: [PluginCommonModule],
+  // We pass our schema extension and any related resolvers
+  // to our plugin metadata  
+  shopApiExtensions: {
+    schema: schemaExtension,
+    resolvers: [TopProductsResolver],
+  },
+  // Likewise, if you want to extend the Admin API,
+  // you would use `adminApiExtensions` in exactly the
+  // same way.  
+})
+export class TopProductsPlugin {}
+```
+
 There are a number of ways the GraphQL APIs can be modified by a plugin.
 
 ## Adding a new Query or Mutation
@@ -76,6 +109,43 @@ extend type Mutation {
 }
 ```
 
+## Defining a new type
+
+If you have [defined a new database entity]({{< relref "defining-db-entity" >}}), it is likely that you'll want to expose this entity in your GraphQL API. To do so, you'll need to define a corresponding GraphQL type:
+
+```TypeScript
+import gql from 'graphql-tag';
+import { PluginCommonModule, VendurePlugin } from '@vendure/core';
+import { ReviewsResolver } from './reviews.resolver';
+import { ProductReview } from './product-review.entity';
+
+@VendurePlugin({
+  imports: [PluginCommonModule],
+  shopApiExtensions: {
+    schema: gql`
+      # This is where we define the GraphQL type
+      # which corresponds to the Review entity
+      type ProductReview implements Node {
+        id: ID!
+        createdAt: DateTime!
+        updatedAt: DateTime!
+        text: String!
+        rating: Float!
+      }
+      
+      extend type Query {
+        # Now we can use this ProductReview type in queries
+        # and mutations.
+        reviewsForProduct(productId: ID!): [ProductReview!]!
+      }
+    `,
+    resolvers: [ReviewsResolver]
+  },
+  entities: [ProductReview],  
+})
+export class ReviewsPlugin {}
+```
+
 ## Add fields to existing types
 
 Let's say you want to add a new field, "availability" to the ProductVariant type, to allow the storefront to display some indication of whether a variant is available to purchase. First you define a resolver function: