docs: add tutorial to expose GraphQL APIs

docs/site/exposing-graphql-apis.md

@@ -0,0 +1,131 @@
+---
+lang: en
+title: 'Exposing GraphQL APIs'
+keywords: LoopBack 4.0, LoopBack 4
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/exposing-graphql-apis.html
+---
+
+## Overview
+
+The [OASGraph module](https://www.npmjs.com/package/oasgraph) creates a GraphQL
+wrapper for existing REST APIs which are described by the OpenAPI specification.
+This tutorial shows how to expose GraphQL APIs in an existing LoopBack
+application.
+
+### Prerequisite
+
+Make sure you have a running LoopBack 4 application. In this tutorial, we'll use
+the `todo` example. You can create this application by running the command
+below:
+
+```sh
+lb4 example todo
+```
+
+### Customize the Server URL of the REST Server
+
+OASGraph expects the provided OpenAPI specification to have the `servers` url to
+be the server hosting the REST endpoints. We're going to modify the constructor
+of `TodoListApplication` in `src/application.ts` to include this information.
+
+```ts
+constructor(options: ApplicationConfig = {}) {
+    // Add this snippet at the beginning of the constructor
+    options = Object.assign(
+      {},
+      {
+        rest: {
+          openApiSpec: {
+            servers: [{url: 'http://localhost:3000'}],
+          },
+        },
+      },
+    );
+    // end of the code snippet
+    super(options);
+    ...
+}
+```
+
+### Install OASGraph and Required Dependencies
+
+From your LoopBack application, run the following command to install OASGraph
+and the required dependencies:
+
+```sh
+npm i --save oasgraph express-graphql
+```
+
+### Start the GraphQL Server
+
+Make sure your LoopBack application is running by going to
+`http://localhost:3000/openapi.json`. If not, you can start it by running the
+`npm start` command.
+
+Now we will use the oasgraph CLI to set up a GraphQL HTTP Server backed by
+express on port 3001. Specifying the OpenAPI spec generated by the
+todo-application as the parameter, start up the server by running the following
+command:
+
+```sh
+node_modules/.bin/oasgraph http://localhost:3000/openapi.json
+```
+
+That’s it! You’re now ready to try out some tests and requests in the browser at
+http://localhost:3001/graphql.
+
+### Try Out the GraphQL APIs
+
+Here are some examples of the `query` and `mutation` calls:
+
+1. To get all the to-do instances, run this query command:
+
+```
+ query{
+   todos {
+     id
+     title
+     desc
+   }
+ }
+```
+
+The expected output looks like this:
+
+```json
+{ "data": { "todos": [ { "id": 1, "title":
+"Take over the galaxy", "desc":
+"MWAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHA" }, { "id": 2, "title":
+"destroy alderaan", "desc": "Make sure there are no survivors left!" }, { "id":
+3, "title": "terrorize senate", "desc": "Tell them they're getting a budget
+cut." }, { "id": 4, "title": "crush rebel scum", "desc": "Every.Last.One." } ] }
+}
+```
+
+2. Create a to-do instance and retrieve its ID and title in the response object
+   using the following mutation command:
+
+```
+ mutation {
+   postTodos(todoInput: {
+     title: "Take over the universe"
+   }) {
+     id
+     title
+   }
+ }
+```
+
+The expected output looks like this:
+
+```json
+{
+  "data": {
+    "postTodos": {
+      "id": 5,
+      "title": "Take over the universe"
+    }
+  }
+}
+```

docs/site/sidebars/lb4_sidebar.yml

@@ -98,6 +98,11 @@ children:
     - title: 'Run and Test it'
       url: soap-calculator-tutorial-run-and-test.html
       output: 'web, pdf'
+
+  - title: 'Exposing GraphQL APIs'
+    url: exposing-graphql-apis.html
+    output: 'web, pdf'
+
   - title: 'Deploying to IBM Cloud'
     url: Deploying-to-IBM-Cloud.html
     output: 'web, pdf'