feat: Update postProcess config to allow alternate save mechanism (#91)

Update `postProcess` configuration to run after tag clean-up phase
to allow an alternate mechanism for saving the generated Swagger to
be specified, rather than the standard writing a file to the filesystem.

Allow `swaggerJsonPath` to be empty/null/undefined, in which case
no file write attempted.

This supports deployment to environments that do not allow writing to the
filesystem e.g. store in memory or database.

Author: danielsharvey

README.MD

@@ -42,7 +42,7 @@ By default, the Swagger Generator Sails Hook generates:
 
 ## Use with [Swagger UI](https://github.com/swagger-api/swagger-ui)
 
-See [#28](https://github.com/theoomoregbee/sails-hook-swagger-generator/issues/28) 
+See [#28](https://github.com/theoomoregbee/sails-hook-swagger-generator/issues/28)
 
 ## Adding/Customising Generated Output
 
@@ -100,7 +100,8 @@ module.exports['swagger-generator'] = {
 Notes on the use of configuration:
 
 * `disabled` attribute is used to disable the module (e.g you may want to disable it on production).
-* `swaggerJsonPath` where to generate the `swagger.json` file to; defaults to `sails.config.appPath + '/swagger/swagger.json'`.
+* `swaggerJsonPath` where to generate the `swagger.json` file to; defaults to `sails.config.appPath + '/swagger/swagger.json'`
+   and output file will not be written if empty/null/undefined (see `postProcess` below for alternate save mechanism).
 * `swagger` object is template for the Swagger/OpenAPI output. It defaults to the minimal content above.
    Check Swagger/OpenAPI specification for more, in case you want to extend it.
    Generally, this hook provides sensible defaults for as much as possible but you may
@@ -111,7 +112,8 @@ Notes on the use of configuration:
   routes be excluded from generated Swagger output; defaults to `true`.
 * `includeRoute` function used to filter routes to be included in generated Swagger output; see advanced section below.
 * `updateBlueprintActionTemplates` allows customisation of the templates used to generate Swagger for blueprints; see advanced section below.
-* `postProcess` allows modification of the generated Swagger output before it is written to the output file; see advanced section below.
+* `postProcess` allows an alternate mechanism for saving and/or modification of the generated Swagger output before it is written to
+   the output file; see advanced section below.
 
 
 ## Custom Route Configuration
@@ -454,6 +456,10 @@ Tags are added to the top-level Swagger/OpenAPI definitions as follows:
 1. Where a tag with the specified name **does** exist, elements _of that tag_ that do not exist are added
    e.g. `description` and `externalDocs` elements.
 
+Note that a final *clean-up* phase is run after processing, which performs the following:
+1. Removal of unreferenced tags; and
+2. Creation of tags referenced but are not defined.
+
 ### Component Element Handling
 
 Elements of components are added to the top-level Swagger/OpenAPI definitions as follows:
@@ -494,7 +500,7 @@ let componentDefinitionReference = {
 Three mechanisms are provided to enable advancing filtering of the Swagger generation process:
 1. An `includeRoute()` function used to filter routes to be included in generated Swagger output.
 1. An `updateBlueprintActionTemplates()` function allows customisation of the templates used to generate Swagger for blueprints.
-1. A `postProcess()` function allows modification of the generated Swagger output before it is written to the output file.
+1. A `postProcess()` function allows an alternate mechanism for saving and/or modification of the generated Swagger output before it is written to the output file.
 
 Each is configured in `config/swaggergenerator.js`.
 
@@ -621,6 +627,12 @@ Note that:
 The final generated Swagger output may be post-processed before it is written to
 the output file using a post-processing function specified as the `postProcess` config option.
 
+For situations where saving the generated swagger documentation JSON to a file is
+not desired/appropriate, the `postProcess` config option may be used to specify
+an alternate save mechanism.
+
+Note that if `swaggerJsonPath` config option is empty/null/undefined the output file will not be written.
+
 For example:
 ```javascript
 module.exports['swagger-generator'] = {

lib/swagger-doc.ts

@@ -96,8 +96,6 @@ export default async (sails: Sails.Sails, sailsRoutes: Array<Sails.Route>, conte
 
   defaults(specifications.components!.parameters, blueprintParameterTemplates);
 
-  if (hookConfig.postProcess) hookConfig.postProcess(specifications);
-
   // clean up of specification, removing unreferenced tags
   const referencedTags = getUniqueTagsFromPath(specifications.paths);
 
@@ -118,11 +116,17 @@ export default async (sails: Sails.Sails, sailsRoutes: Array<Sails.Route>, conte
     }
   });
 
+  if (hookConfig.postProcess) {
+    hookConfig.postProcess(specifications);
+  }
+
   const destPath = hookConfig.swaggerJsonPath;
-  try {
-    fs.writeFileSync(destPath, JSON.stringify(specifications, null, 2));
-  } catch (e) {
-    sails.log.error(`ERROR: sails-hook-swagger-generator: Error writing ${destPath}: ${e.message}`, e);
+  if (destPath) {
+    try {
+      fs.writeFileSync(destPath, JSON.stringify(specifications, null, 2));
+    } catch (e) {
+      sails.log.error(`ERROR: sails-hook-swagger-generator: Error writing ${destPath}: ${e.message}`, e);
+    }
   }
 
   sails.log.info('Swagger generated successfully');