GraphQL custom schema on CLI (#5828)

* Add --graphQLSchema to CLI

* Add custom graphql schema instructions to readme file

* Update README.md

Co-Authored-By: Tom Fox <[email protected]>

* Update src/Options/Definitions.js

Co-Authored-By: Tom Fox <[email protected]>

* Update src/Options/docs.js

Co-Authored-By: Tom Fox <[email protected]>

* Update src/Options/index.js

Co-Authored-By: Tom Fox <[email protected]>

Author: davimacedo

README.md

@@ -361,7 +361,7 @@ Take a look at [Live Query Guide](https://docs.parseplatform.org/parse-server/gu
 
 # GraphQL
 
-[GraphQL](https://graphql.org/), developed by Facebook, is an open-source data query and manipulation language for APIs. In addition to the traditional REST API, Parse Server automatically generates a GraphQL API based on your current application schema.
+[GraphQL](https://graphql.org/), developed by Facebook, is an open-source data query and manipulation language for APIs. In addition to the traditional REST API, Parse Server automatically generates a GraphQL API based on your current application schema. Parse Server also allows you to define your custom GraphQL queries and mutations, whose resolvers can be bound to your cloud code functions.
 
 ## Running
 
@@ -555,6 +555,52 @@ You should receive a response similar to this:
 }
 ```
 
+## Customizing your GraphQL Schema
+
+Parse GraphQL Server allows you to create a custom GraphQL schema with own queries and mutations to be merged with the auto-generated ones. You can resolve these operations using your regular cloud code functions.
+
+To start creating your custom schema, you need to code a `schema.graphql` file and initialize Parse Server with `--graphQLSchema` and `--cloud` options:
+
+```bash
+$ parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://localhost/test --mountGraphQL --mountPlayground --graphQLSchema ./schema.graphql --cloud ./main.js
+```
+
+### Creating your first custom query
+
+Use the code below for your `schema.graphql` and `main.js` files. Then restart your Parse Server.
+
+```graphql
+# schema.graphql
+extend type Query {
+  hello: String! @resolve
+}
+```
+
+```js
+// main.js
+Parse.Cloud.define('hello', async () => {
+  return 'Hello world!';
+});
+```
+
+You can now run your custom query using GraphQL Playground:
+
+```graphql
+query {
+  hello
+}
+```
+
+You should receive the response below:
+
+```json
+{
+  "data": {
+    "hello": "Hello world!"
+  }
+}
+```
+
 ## Learning more
 
 The [Parse GraphQL Guide](http://docs.parseplatform.org/graphql/guide/) is a very good source for learning how to use the Parse GraphQL API.

src/Options/Definitions.js

@@ -158,6 +158,10 @@ module.exports.ParseServerOptions = {
     help: 'Mount path for the GraphQL endpoint, defaults to /graphql',
     default: '/graphql',
   },
+  graphQLSchema: {
+    env: 'PARSE_SERVER_GRAPH_QLSCHEMA',
+    help: 'Full path to your GraphQL custom schema.graphql file',
+  },
   host: {
     env: 'PARSE_SERVER_HOST',
     help: 'The host to serve ParseServer on, defaults to 0.0.0.0',

src/Options/docs.js

@@ -28,6 +28,7 @@
  * @property {String} fileKey Key for your files
  * @property {Adapter<FilesAdapter>} filesAdapter Adapter module for the files sub-system
  * @property {String} graphQLPath Mount path for the GraphQL endpoint, defaults to /graphql
+ * @property {String} graphQLSchema Full path to your GraphQL custom schema.graphql file
  * @property {String} host The host to serve ParseServer on, defaults to 0.0.0.0
  * @property {String} javascriptKey Key for the Javascript SDK
  * @property {Boolean} jsonLogs Log as structured JSON objects

src/Options/index.js

@@ -180,6 +180,8 @@ export interface ParseServerOptions {
   startLiveQueryServer: ?boolean;
   /* Live query server configuration options (will start the liveQuery server) */
   liveQueryServerOptions: ?LiveQueryServerOptions;
+  /* Full path to your GraphQL custom schema.graphql file */
+  graphQLSchema: ?string;
   /* Mounts the GraphQL endpoint
   :ENV: PARSE_SERVER_MOUNT_GRAPHQL
   :DEFAULT: false */

src/ParseServer.js

@@ -5,7 +5,9 @@ var batch = require('./batch'),
   express = require('express'),
   middlewares = require('./middlewares'),
   Parse = require('parse/node').Parse,
-  path = require('path');
+  { parse } = require('graphql'),
+  path = require('path'),
+  fs = require('fs');
 
 import { ParseServerOptions, LiveQueryServerOptions } from './Options';
 import defaults from './defaults';
@@ -267,9 +269,17 @@ class ParseServer {
     app.use(options.mountPath, this.app);
 
     if (options.mountGraphQL === true || options.mountPlayground === true) {
+      let graphQLCustomTypeDefs = undefined;
+      if (options.graphQLSchema) {
+        graphQLCustomTypeDefs = parse(
+          fs.readFileSync(options.graphQLSchema, 'utf8')
+        );
+      }
+
       const parseGraphQLServer = new ParseGraphQLServer(this, {
         graphQLPath: options.graphQLPath,
         playgroundPath: options.playgroundPath,
+        graphQLCustomTypeDefs,
       });
 
       if (options.mountGraphQL) {