Fixed some problems with the documentation

Signed-off-by: Alan Cha <[email protected]>

Author: Alan-Cha

README.md

@@ -12,12 +12,14 @@ Turns APIs described by OpenAPI specifications (OAS) into GraphQL interfaces.
 
 An example application exposing GitHub's public REST-like API via OASGraph can be found [here](https://oasgraph-github.mybluemix.net/) ([source code](https://github.ibm.com/apiharmony/oasgraph-oauth-github-example)).
 
+
 ## Getting started
 
 * [Quickstart guide](./docs/tutorials/quickstart.md): Learn how to quickly spin up GraphQL wrappers using the OASGraph CLI.
 * [Library tutorial](./docs/tutorials/watson.md): Learn how to use OASGraph as a library, and how to improve the resulting GraphQL wrappers using OAS `link` definitions.
 * [LoopBack tutorial](./docs/tutorials/loopback_tutorial.md): Learn how to use OASGraph to create GraphQL wrappers for APIs created with LoopBack 4.
 
+
 ## Characteristics
 
 * **Data-centric**
@@ -95,19 +97,30 @@ OASGraph.createGraphQlSchema(oas)
 
 ***
 
-Alternatively, use the CLI tool.
+Alternatively, use the CLI tool, which will run OASGraph on a specified OAS and start a server to host the GraphQL interface.
 
-```
-Usage: oasgraph <OAS JSON file path>
+You can specify a local file containing the OAS specification or a remote url such as `http://127.0.0.1:3000/openapi.json`. Additionally, you can specify an optional port number so you can have multiple GraphQL servers for testing in the same machine.
+
+```sh
+oasgraph <OAS JSON file path or remote url> [port number]
 ```
 
 To create the CLI tool, run:
-```
+```sh
 npm link
 ```
 
 Please note that the CLI tool is mainly used for quick testing and does not offer all the features that `createGraphQlSchema(oas, options)` does.
 
+***
+
+OASgraph can also generate and save the GraphQL schema to the local file `schema.graphql`, which you can use later to inspect or change its content. Please note that the following command will not start the GraphQL server.
+
+```sh
+oasgraph <OAS JSON file path or remote url> --save
+```
+
+
 ## Options
 OASGraph allows to define an optional `options` object:
 
@@ -187,13 +200,15 @@ OASGraph further provides `anyAuth` viewers (for queries and mutations), which a
 }
 ```
 
+
 ## Authorization
 OASGraph now supports OAuth 2.0!
 
 Because OASGraph is a library, it cannot make the callbacks that OAuth requires by itself. Instead, the user must take care of the callback. After the user has obtained the OAuth token from the callback, simply pass the token, specifically the path of the token, to OASGraph through the `tokenJSONpath` [option](./README.md#options).
 
 To see an example of how this would work, click [here](https://github.ibm.com/apiharmony/oasgraph-oauth-github-example)!
 
+
 ## Testing
 To test OASGraph, run:
 
@@ -203,7 +218,8 @@ npm test
 
 This command will temporarily start and later shut down an example REST(-like) API.
 
-### Research
+
+## Research
 Our research paper, "Generating GraphQL-Wrappers for REST(-like) APIs", can be found [here](https://arxiv.org/abs/1809.08319). The paper describes the challenges of building OASGraph and an experiment in which we evaluated OASGraph against 959 publicly available OAS, provided by [APIs.guru](https://apis.guru/), and successfully created GraphQL interfaces for 89.5% of them.
 
 To run the experiment, load APIs.guru specifications, found [here](https://github.com/APIs-guru/openapi-directory), into the `/tmp` folder:
@@ -245,5 +261,6 @@ OASGraph is written in [TypeScript](http://www.typescriptlang.org/). All source
 
 * [StackOverflow discussion](https://stackoverflow.com/questions/38339442/json-schema-to-graphql-schema-converters) points to the above projects.
 
+
 ## License
 [MIT](./LICENSE.md)

docs/tutorials/quickstart.md

@@ -2,7 +2,7 @@
 
 The purpose of this tutorial is to show how easy it is to use OASGraph.
 
-With just a single command line instruction, `oasgraph [path]`, you can get a GraphQL server running.
+With just a single command line instruction, `oasgraph <OAS JSON file path or remote url>`, you can get a GraphQL server running.
 
 Please note that while the CLI tool will satisfy most needs, it does not offer the flexibility or functionality of OASGraph's intended usage, as an integrated library. See the [README.md](../../README.md) for more information.
 
@@ -34,30 +34,21 @@ OASGraph relies on the OpenAPI Specification (OAS) of an existing API to create
 
 If you are using LoopBack, you can simply copy the URL location of the web-hosted OAS, which is usually http://127.0.0.1:3000/openapi.json.
 
-# in the LoopBack project folder:
-
 ```sh
+# in the LoopBack project folder:
 npm start
 ```
 
 ***
 
-If you want to generate a GraphQL interface for another API, make sure that API is running and proceed in the same way.
+If you want to generate a GraphQL interface for another API, make sure that API is running and proceed in the same way or save the OAS.
 
 ### Start GraphQL server
 
 Once OASGraph is installed and the OAS is obtained, you can create and start the GraphQL server. The created GraphQL server is then accessible by default at [http://127.0.0.1:3001/graphql](http://127.0.0.1:3001/graphql).
 
-You can specify a local file containing the OAS specification or a remote url such as `http://127.0.0.1:3000/openapi.json` and an optional port number, this way you can have multiple GraphQL servers for testing in the same machine.
+You can specify a local file containing the OAS specification or a remote url such as `http://127.0.0.1:3000/openapi.json`. Additionally, you can specify an optional port number so you can have multiple GraphQL servers for testing in the same machine.
 
 ```sh
 oasgraph <OAS JSON file path or remote url> [port number]
 ```
-
-### Export a GraphQL schema
-
-OASgraph can also generate and save the GraphQL schema to the local file `schema.graphql`, which you can use later to inspect or change its content in the editor of your choice. Please note that the following command will not start the GraphQL server.
-
-```sh
-oasgraph <OAS JSON file path or remote url> --save
-```