Documentation changes

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

Author: Alan-Cha

packages/openapi-to-graphql/README.md

@@ -178,8 +178,8 @@ Resolver options:
 
 - `customResolvers` (type: `object`, default: `{}`): OpenAPI-to-GraphQL, by default, creates resolver functions that make REST calls to resolve fields in the generated GraphQL interface. This option allows users to provide custom resolver functions to be used in place of said ones created by OpenAPI-to-GraphQL. The field that the custom resolver will affect is identifed first by the [title](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject) of the OAS, then the [path](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#paths-object) of the operation, and lastly the [method](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#path-item-object) of the operation. The `customResolvers` object is thus a triply nested object where the outer key is the title, followed by the path, and finally the method, which points to the [resolver function](https://graphql.org/learn/execution/#root-fields-resolvers) itself. The resolver function can use the parameters `obj`, `args`, `context`, and `info` in order to produce the proper data, as do standard [resolver functions](https://graphql.org/learn/execution/#root-fields-resolvers) in GraphQL. Use cases include the resolution of complex relationships between types, implementing performance improvements like caching, or dealing with non-standard authentication requirements. _Note: Because the arguments are provided by the GraphQL interface, they may look different from the [parameters](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject) defined by the OAS. For example, they will have [sanitized](https://github.com/Alan-Cha/openapi-to-graphql#characteristics) names. The [request body](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#requestBodyObject) will also be contained in the arguments as an [input object type](https://graphql.org/graphql-js/mutations-and-input-types/)._
 
-- `createSubscriptionsFromCallbacks` (type: `boolean`, default: `false`): Allow to generate subscription fields from CallbackObjects in OpenAPI schema. Path ( runtime expression ) of the [CallbackObject](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#CallbackObject) will be interpolated as topic of publish / subscription to use with a [pubsub](https://github.com/apollographql/graphql-subscriptions) instance.
-Read the [doc](./docs/SUBSCRIPTIONS.md) for explanations and examples regarding its usage.
+- `createSubscriptionsFromCallbacks` (type: `boolean`, default: `false`): Generates subscription fields from [callback objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#CallbackObject). The keys ([runtime expressions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#runtimeExpression)) of the callback objects will be interpolated as the topic of a publish/subscription connection using [graphql-subscriptions](https://github.com/apollographql/graphql-subscriptions). Read the [doc](./docs/SUBSCRIPTIONS.md) for explanations and examples regarding its usage.
+
 ***
 
 Authentication options:

packages/openapi-to-graphql/docs/SUBSCRIPTIONS.md

@@ -1,9 +1,9 @@
 # Subscriptions with OpenAPI-to-GraphQL
-Since version x.x.x, OpenAPI-to-GraphQL supports [GraphQL _subscription_ operations](http://spec.graphql.org/draft/#sec-Subscription). In GraphQL, using a subscription query, clients subscribe to updates on the data defined in the query. In this scneario, when data changes, the server publishes these changes to all clients that have active subscriptions for that data.
+Since version 2.1.0, OpenAPI-to-GraphQL supports [GraphQL _subscription_ operations](http://spec.graphql.org/draft/#sec-Subscription). In GraphQL, using a subscription query, clients subscribe to updates on the data defined in the query. In this scneario, when data changes, the server publishes these changes to all clients that have active subscriptions for that data.
 
 The OpenAPI specification can define similar behavior using [callbacks](https://swagger.io/specification/#callbackObject): a callback defines a request that the server may initiate in response to receiving another request. Callbacks can thus be used to model publish/subscribe behavior. I.e., when the server receives a request to update some data, it can then itself issue callback requests (outside of the first request/response cycle) to any number of subscribed clients to inform about the new data.
 
-When enabling the `createSubscriptionsFromCallbacks` option, OpenAPI-to-GraphQL creates a subscription field for any operation in the given OpenAPI document that defines a `callback` object. In such cases, OpenAPI-to-GraphQL creates a [subscribe](http://spec.graphql.org/draft/#Subscribe()) function responsible to subscribing clients to receive results of callbacks being executed, and a special form of a [resolve](http://spec.graphql.org/draft/#ResolveFieldEventStream()) function, which pushes data updates to subscribed clients.
+When the [`createSubscriptionsFromCallbacks` option](https://github.com/IBM/openapi-to-graphql/tree/master/packages/openapi-to-graphql#options) is enabled, OpenAPI-to-GraphQL creates subscription fields from an operation's callback objects. In such cases, OpenAPI-to-GraphQL creates a [subscribe](http://spec.graphql.org/draft/#Subscribe()) function responsible to subscribing clients to receive results of callbacks being executed, and a special form of a [resolve](http://spec.graphql.org/draft/#ResolveFieldEventStream()) function, which pushes data updates to subscribed clients.
 
 To create these two functions, OpenAPI-to-GraphQL relies on the popular [graphql-subscriptions](https://github.com/apollographql/graphql-subscriptions) package, which provides a unified API to support different network transports (like WebSockets, MQTT, Redis etc. - see this [list of supported transports](https://github.com/apollographql/graphql-subscriptions#pubsub-implementations)).
 
@@ -22,7 +22,7 @@ const eventEmitter = new EventEmitter2({
   delimiter: '/'
 });
 
-// Create the PubSub instance ( here by wrapping an EventEmitter client )
+// Create the PubSub instance (here by wrapping an EventEmitter client)
 const pubsub = new PubSub()
 
 export default pubsub
@@ -36,7 +36,7 @@ import { MQTTPubSub } = from 'graphql-mqtt-subscriptions'
 
 const MQTT_PORT = 1883
 
-// Create a PubSub instance ( here by wrapping a MQTT client )
+// Create a PubSub instance (here by wrapping a MQTT client)
 const client = connect(`mqtt://localhost:${MQTT_PORT}`)
 
 const pubsub = new MQTTPubSub({
@@ -86,8 +86,7 @@ const init = async () => {
         subscribe,
         schema,
         onConnect: (params, socket, ctx) => {
-          // adding pubsub to context
-          // to be used by graphQL subscribe field
+          // Add pubsub to context to be used by GraphQL subscribe field
           return { pubsub }
         }
       },
@@ -104,7 +103,7 @@ init()
 
 ## API server
 
-A simple example could be the following, when an HTTP client tries to create a device ( via `post('/api/devices')` route ) an event is published by the PubSub instance.
+A simple example could be the following, when an HTTP client tries to create a device (via `post('/api/devices')` route) an event is published by the PubSub instance.
 If a callback like [#/components/callbacks/DevicesEvent](../test/fixtures/example_oas5.json) is declared in your OpenAPI schema and used in path `/devices` for the `post` Operation, a subscription field will be generated by OpenAPI-to-GraphQL.
 
 
@@ -147,7 +146,7 @@ const startServer = () => {
           payload: Buffer.from(JSON.stringify(device))
         }
 
-        // use pubsub to publish the event
+        // Use pubsub to publish the event
         pubsub.publish(packet)
 
         res.status(200).send(device)
@@ -192,8 +191,7 @@ const device = {
 }
 
 const startClient = () => {
-  // generate subscription :
-  // via GraphQL WS API
+  // Generate subscription via GraphQL WS API...
   const client = new SubscriptionClient(
     `ws://localhost:${GRAPHQL_HTTP_PORT}/subscriptions`
   )
@@ -220,15 +218,13 @@ const startClient = () => {
     },
   })
 
-  // or directly via PubSub instance
-  // like OpenAPI-to-GraphQL would do
+  // ...or directly via PubSub instance like OpenAPI-to-GraphQL would do
   pubsub.subscribe(`/api/${device.userName}/devices/POST/*`, (...args) => {
     console.log('Device created', args)
   })
 
 
-  // trigger device creation:
-  // via GraphQL HTTP API
+  // Trigger device creation via GraphQL HTTP API...
   axios({
     url: `http://localhost:${GRAPHQL_HTTP_PORT}/graphql`,
     method: 'POST',
@@ -244,8 +240,7 @@ const startClient = () => {
     },
   })
 
-  // or via REST API
-  // like OpenAPI-to-GraphQL would do
+  // ...or via REST API like OpenAPI-to-GraphQL would do
   axios({
     url: `http://localhost:${REST_HTTP_PORT}/api/devices`,
     method: 'POST',
@@ -260,9 +255,9 @@ startClient()
 In this example, we rely on the [`subscriptions-transport-ws` package](https://github.com/apollographql/subscriptions-transport-ws) to create a `SubscriptionServer` that manages WebSockets connections between the GraphQL clients and our server. We also rely on the `graphqlExpress` server provided by the [`apollo-server-express` package](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-express) to serve GraphQL from Express.js.
 
 
-Sidenote concerning callback, as you can see in the example Callback, the path (runtime expression) `/api/{$request.body#/userName}/devices/{$request.body#/method}/+` is delimited by `/` and ends with `+`, these symbols are interpreted as delimiters and wildcard when using MQTT topics.
+Concerning callbacks, as you can see in the example, the path (runtime expression) `/api/{$request.body#/userName}/devices/{$request.body#/method}/+` is delimited by `/` and ends with `+`, these symbols are interpreted as delimiters and wildcard when using MQTT topics.
 It needs to be adapted accordingly to the client wrapped in your PubSub instance, for eventEmitter2 you can use `*` and define your own delimiter.
-An helper might be provided in the future, to simplify this process.
+A helper might be provided in the future, to simplify this process.
 
 ## Examples