feat(docs): Update to reflect new API structure

Relates to #65

.gitignore

@@ -404,3 +404,5 @@ docs/content/docs/configuration/*
 !docs/content/docs/configuration/_index.md
 docs/content/docs/graphql-api/*
 !docs/content/docs/graphql-api/_index.md
+!docs/content/docs/graphql-api/shop/_index.md
+!docs/content/docs/graphql-api/admin/_index.md

codegen/generate-api-docs.ts

@@ -18,12 +18,16 @@ import { deleteGeneratedDocs, generateFrontMatter } from './docgen-utils';
 
 // tslint:disable:no-console
 
+type TargetApi = 'shop' | 'admin';
+
+const targetApi: TargetApi = getTargetApiFromArgs();
+
 // The path to the introspection schema json file
-const SCHEMA_FILE = path.join(__dirname, '../schema.json');
+const SCHEMA_FILE = path.join(__dirname, `../schema-${targetApi}.json`);
 // The absolute URL to the generated api docs section
-const docsUrl = '/docs/graphql-api/';
+const docsUrl = `/docs/graphql-api/${targetApi}/`;
 // The directory in which the markdown files will be saved
-const outputPath = path.join(__dirname, '../docs/content/docs/graphql-api');
+const outputPath = path.join(__dirname, `../docs/content/docs/graphql-api/${targetApi}`);
 
 const enum FileName {
     ENUM = 'enums',
@@ -35,7 +39,7 @@ const enum FileName {
 
 const schemaJson = fs.readFileSync(SCHEMA_FILE, 'utf8');
 const parsed = JSON.parse(schemaJson);
-const schema = buildClientSchema(parsed.data);
+const schema = buildClientSchema(parsed.data ? parsed.data : parsed);
 
 deleteGeneratedDocs(outputPath);
 generateApiDocs(outputPath);
@@ -57,6 +61,9 @@ function generateApiDocs(hugoOutputPath: string) {
         if (isObjectType(type)) {
             if (type.name === 'Query') {
                 for (const field of Object.values(type.getFields())) {
+                    if (field.name === 'temp__') {
+                        continue;
+                    }
                     queriesOutput += `## ${field.name}\n`;
                     queriesOutput += renderDescription(field);
                     queriesOutput += renderFields([field], false) + '\n\n';
@@ -172,3 +179,13 @@ function unwrapType(type: GraphQLType): GraphQLNamedType {
     }
     return innerType;
 }
+
+function getTargetApiFromArgs(): TargetApi {
+    const apiArg = process.argv.find(arg => /--api=(shop|admin)/.test(arg));
+    if (!apiArg) {
+        console.error(`\nPlease specify which GraphQL API to generate docs for: --api=<shop|admin>\n`);
+        process.exit(1);
+        return null as never;
+    }
+    return apiArg === '--api=shop' ? 'shop' : 'admin';
+}

docs/content/docs/graphql-api/_index.md

@@ -8,6 +8,7 @@ showtoc: false
 
 This section contains a description of all queries, mutations and related types available in the Vendure GraphQL API.
 
+The API is split into two distinct endpoints: *Shop* and *Admin*. The Shop API is for storefront client applications, whereas the Admin API is used for administrative tasks.
 {{% alert %}}
 All documentation in this section is auto-generated from the Vendure GraphQL schema.
 {{% /alert %}}

docs/content/docs/plugins/default-search-plugin.md

@@ -16,5 +16,5 @@ const config: VendureConfig = {
 ```
 
 {{% alert "warning" %}}
-Note that the current implementation of the DefaultSearchPlugin is only implemented and tested against a MySQL/MariaDB database. In addition, the search result quality has not yet been optimized.
+Note that the quality of the fulltext search capabilities varies depending on the underlying database being used. For example, the MySQL & Postgres implementations will typically yield better results than the SQLite implementation.
 {{% /alert %}}

docs/content/docs/plugins/writing-a-vendure-plugin.md

@@ -68,29 +68,29 @@ The `@Injectable()` decorator is part of the underlying [Nest framework](https:/
 To use decorators with TypeScript, you must set the "emitDecoratorMetadata" and "experimentalDecorators" compiler options to `true` in your tsconfig.json file.
 {{% /alert %}}
 
-### Step 3: Extend the GraphQL API
+### Step 3: Define the new mutation
 
-Next we will extend the Vendure GraphQL API to add our new mutation. This is done by implementing the [`defineGraphQlTypes` method](({{< relref "vendure-plugin" >}}#definegraphqltypes)) in our plugin.
+Next we will define how the GraphQL API should be extended:
 
 ```ts 
 import gql from 'graphql-tag';
 
 export class RandomCatPlugin implements VendurePlugin {
 
+    private schemaExtension = gql`
+        extend type Mutation {
+            addRandomCat(id: ID!): Product!
+        }
+    `;
+
     configure(config) {
         // as above
     }
-
-    defineGraphQlTypes() {
-        return gql`
-            extend type Mutation {
-                addRandomCat(id: ID!): Product!
-            }
-        `;
-    }
 }
 ```
 
+We will use this private `schemaExtension` variable in a later step.
+
 ### Step 4: Create a resolver
 
 Now that we've defined the new mutation, we'll need a resolver function to handle it. To do this, we'll create a new resolver class, following the [Nest GraphQL resolver architecture](https://docs.nestjs.com/graphql/resolvers-map). In short, this will be a class which has the `@Resolver()` decorator and features a method to handle our new mutation.
@@ -121,32 +121,44 @@ Some explanations of this code are in order:
 * The `@Resolver()` decorator tells Nest that this class contains GraphQL resolvers.
 * We are able to use Nest's dependency injection to inject an instance of our `CatFetcher` class into the constructor of the resolver. We are also injecting an instance of the built-in `ProductService` class, which is responsible for operations on Products.
 * We use the `@Mutation()` decorator to mark this method as a resolver for a mutation with the corresponding name.
-* The `@Allow()` decorator enables us to define permissions restrictions on the mutation. Only those users whose permissions include `UpdateCatalog` may perform this operation. For a full list of available permissions, see the [Permission enum]({{< relref "enums" >}}#permission).
+* The `@Allow()` decorator enables us to define permissions restrictions on the mutation. Only those users whose permissions include `UpdateCatalog` may perform this operation. For a full list of available permissions, see the [Permission enum]({{< relref "../graphql-api/admin/enums" >}}#permission).
 * The `@Ctx()` decorator injects the current `RequestContext` into the resolver. This provides information about the current request such as the current Session, User and Channel. It is required by most of the internal service methods.
 * The `@Args()` decorator injects the arguments passed to the mutation as an object.
 
-### Step 5: Export the providers
+### Step 5: Export any providers used in the resolver
 
-In order that the Vendure server (and the underlying Nest framework) is able to use the `CatFetcher` and `RandomCatResolver` classes, we must export them via the [`defineProviders` method](({{< relref "vendure-plugin" >}}#defineproviders)) in our plugin:
+In order that out resolver is able to use Nest's dependency injection to inject and instance of `CatFetcher`, we must export it via the [`defineProviders` method](({{< relref "vendure-plugin" >}}#defineproviders)) in our plugin:
 
 ```ts 
 export class RandomCatPlugin implements VendurePlugin {
 
-    configure(config) {
-        // as above
-    }
+    // ...
 
-    defineGraphQlTypes() {
-        // as above
+    defineProviders() {
+        return [CatFetcher];
     }
+}
+```
 
-    defineProviders() {
-        return [CatFetcher, RandomCatResolver];
+### Step 6: Extend the GraphQL API
+
+Now that we've defined the new mutation and we have a resolver capable of handling it, we just need to tell Vendure to extend the API. This is done with the [`extendAdminAPI` method]({{< relref "vendure-plugin" >}}#extendadminapi). If we wanted to extend the Shop API, we'd use the [`extendShopAPI` method]({{< relref "vendure-plugin" >}}#extendshopapi) method instead.
+
+```ts 
+export class RandomCatPlugin implements VendurePlugin {
+
+    // ...
+    
+    extendAdminAPI() {
+        return {
+            schema: this.schemaExtension,
+            resolvers: [RandomCatResolver],
+        };
     }
 }
 ```
 
-### Step 6: Add the plugin to the Vendure config
+### Step 7: Add the plugin to the Vendure config
 
 Finally we need to add an instance of our plugin to the config object with which we bootstrap out Vendure server:
 
@@ -161,9 +173,9 @@ bootstrap({
 });
 ```
 
-### Step 7: Test the plugin
+### Step 8: Test the plugin
 
-Once we have started the Vendure server with the new config, we should be able to send the following GraphQL query:
+Once we have started the Vendure server with the new config, we should be able to send the following GraphQL query to the Admin API:
 
 ```GraphQL
 mutation {
@@ -203,6 +215,13 @@ import http from 'http';
 import { Allow, Ctx, Permission, ProductService, RequestContext, VendureConfig, VendurePlugin } from '@vendure/core';
 
 export class RandomCatPlugin implements VendurePlugin {
+
+    private schemaExtension = gql`
+        extend type Mutation {
+            addRandomCat(id: ID!): Product!
+        }
+    `;
+
     configure(config: Required<VendureConfig>) {
         config.customFields.Product.push({
             type: 'string',
@@ -211,16 +230,15 @@ export class RandomCatPlugin implements VendurePlugin {
         return config;
     }
 
-    defineGraphQlTypes() {
-        return gql`
-            extend type Mutation {
-                addRandomCat(id: ID!): Product!
-            }
-        `;
+    defineProviders() {
+        return [CatFetcher];
     }
 
-    defineProviders() {
-        return [CatFetcher, RandomCatResolver];
+    extendAdminAPI() {
+        return {
+            schema: this.schemaExtension,
+            resolvers: [RandomCatResolver],
+        };
     }
 }
 

package.json

@@ -8,7 +8,7 @@
     "docs:deploy": "cd docs && yarn && cd .. && yarn docs:build",
     "generate-gql-types": "ts-node ./codegen/generate-graphql-types.ts",
     "generate-config-docs": "ts-node ./codegen/generate-config-docs.ts",
-    "generate-api-docs": "ts-node ./codegen/generate-api-docs.ts",
+    "generate-api-docs": "ts-node ./codegen/generate-api-docs.ts --api=shop && ts-node ./codegen/generate-api-docs.ts --api=admin",
     "test": "cd admin-ui && yarn test --watch=false --browsers=ChromeHeadlessCI --progress=false && cd ../server && yarn test && yarn test:e2e",
     "format": "prettier --write --html-whitespace-sensitivity ignore",
     "lint:server": "cd server && yarn lint --fix",

server/src/config/vendure-plugin/vendure-plugin.ts

@@ -14,7 +14,9 @@ export type InjectorFn = <T>(type: Type<T>) => T;
 /**
  * @description
  * An object which allows a plugin to extend the Vendure GraphQL API.
- */
+ *
+ * @docsCategory plugin
+ * */
 export interface APIExtensionDefinition {
     /**
      * @description

shared/generated-shop-types.ts

@@ -1,5 +1,5 @@
 // tslint:disable
-// Generated in 2019-02-21T12:58:37+01:00
+// Generated in 2019-02-22T10:57:55+01:00
 export type Maybe<T> = T | null;
 
 export interface OrderListOptions {

shared/generated-types.ts

@@ -1,5 +1,5 @@
 // tslint:disable
-// Generated in 2019-02-21T12:58:38+01:00
+// Generated in 2019-02-22T10:57:56+01:00
 export type Maybe<T> = T | null;