feat: Add option to excluded deprecated PUT update blueprint (default) (#73)

* feat: Add option to excluded deprecated `PUT update` blueprint (default)

Sails 1.0 includes `PUT` and `PATCH` routes to the `update` blueprint
although `PUT` deprecated; default to excluding the `PUT` route.

See
- https://sailsjs.com/documentation/reference/blueprint-api/update#?notes
- https://github.com/balderdashy/sails/blob/master/lib/hooks/blueprints/index.js#L401

Co-authored-by: Theophilus Omoregbee <[email protected]>

Author: danielsharvey

README.MD

@@ -85,6 +85,7 @@ module.exports['swagger-generator'] = {
             '500': { description: 'Internal server error' }
         }
     },
+    excludeDeprecatedPutBlueprintRoutes: true,
     includeRoute: function(routeInfo) { return true; },
     updateBlueprintActionTemplates: function(blueprintActionTemplates) { ... },
     postProcess: function(specifications) { ... }
@@ -100,6 +101,9 @@ Notes on the use of configuration:
    Generally, this hook provides sensible defaults for as much as possible but you may
    override them in this location or in any of the mechanisms explained below.
 * `defaults` object should contain the `responses` element; defaults to the above if not specified.
+* `excludeDeprecatedPutBlueprintRoutes` should
+  [deprecated](https://sailsjs.com/documentation/reference/blueprint-api/update#?notes) `PUT` blueprint
+  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.

index.ts

@@ -30,7 +30,8 @@ module.exports = (sails: Sails.Sails): Sails.Hook<SwaggerGenerator> => {
             { url: 'http://localhost:1337/' }
           ],
           externalDocs: { url: 'https://theoomoregbee.github.io/' }
-        }
+        },
+        excludeDeprecatedPutBlueprintRoutes: true,
       }
     },
     // Run when sails loads-- be sure and call `next()`.

lib/interfaces.ts

@@ -3,13 +3,14 @@ import { OpenApi } from '../types/openapi';
 import { Reference, Tag, ExternalDocs } from 'swagger-schema-official';
 
 export interface SwaggerGenerator {
-    includeRoute?: (route: SwaggerRouteInfo) => boolean;
-    disabled?: boolean;
-    swaggerJsonPath: string;
-    swagger: Omit<OpenApi.OpenApi, 'paths'>;
-    updateBlueprintActionTemplates?: (template: BlueprintActionTemplates) => BlueprintActionTemplates;
-    defaults?: Defaults;
-    postProcess?: (specification: OpenApi.OpenApi) => void;
+  includeRoute?: (route: SwaggerRouteInfo) => boolean;
+  disabled?: boolean;
+  swaggerJsonPath: string;
+  swagger: Omit<OpenApi.OpenApi, 'paths'>;
+  updateBlueprintActionTemplates?: (template: BlueprintActionTemplates) => BlueprintActionTemplates;
+  defaults?: Defaults;
+  postProcess?: (specification: OpenApi.OpenApi) => void;
+  excludeDeprecatedPutBlueprintRoutes?: boolean;
 }
 
 /**

lib/swagger-doc.ts

@@ -57,6 +57,16 @@ export default async (sails: Sails.Sails, sailsRoutes: Array<Sails.Route>, conte
     routes = routes.filter(route => hookConfig.includeRoute!(route));
   }
 
+  /*
+   * Sails 1.0 includes `PUT` and `PATCH` routes to the `update` blueprint although `PUT` deprecated;
+   * default to excluding the `PUT` route.
+   * @see https://sailsjs.com/documentation/reference/blueprint-api/update#?notes
+   * @see https://github.com/balderdashy/sails/blob/master/lib/hooks/blueprints/index.js#L401
+   */
+  if(hookConfig.excludeDeprecatedPutBlueprintRoutes) {
+    routes = routes.filter(route => !(route.actionType === 'blueprint' && route.action === 'update' && route.verb === 'put'));
+  }
+
   mergeModelJsDoc(models, modelsJsDoc);
   mergeControllerJsDoc(controllers, controllersJsDoc);
 

test/fixtures/generatedSwagger.json

@@ -2112,51 +2112,6 @@
             "description": "Internal server error"
           }
         }
-      },
-      "put": {
-        "summary": "Update Pet",
-        "description": "Update an existing **Pet** record.",
-        "externalDocs": {
-          "url": "https://sailsjs.com/documentation/reference/blueprint-api/update",
-          "description": "See https://sailsjs.com/documentation/reference/blueprint-api/update"
-        },
-        "tags": [
-          "Pet"
-        ],
-        "parameters": [
-          {
-            "$ref": "#/components/parameters/ModelPKParam-pet"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Responds with the newly updated **Pet** record as a JSON dictionary",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/pet"
-                }
-              }
-            }
-          },
-          "404": {
-            "description": "Cannot update, **Pet** record with specified ID **NOT** found"
-          },
-          "500": {
-            "description": "Internal server error"
-          }
-        },
-        "requestBody": {
-          "description": "JSON dictionary representing the Pet instance to update.",
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/pet-without-required-constraint"
-              }
-            }
-          }
-        }
       }
     },
     "/pet/{_petID}/{association}": {
@@ -2396,52 +2351,6 @@
             "description": "Internal server error"
           }
         }
-      },
-      "put": {
-        "summary": "Update User",
-        "description": "Update an existing **User** record.",
-        "externalDocs": {
-          "url": "https://somewhere.com/yep",
-          "description": "Refer to these docs for more info"
-        },
-        "tags": [
-          "User (ORM duplicate)",
-          "User (ORM)"
-        ],
-        "parameters": [
-          {
-            "$ref": "#/components/parameters/ModelPKParam-user"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Responds with the newly updated **User** record as a JSON dictionary",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/user"
-                }
-              }
-            }
-          },
-          "404": {
-            "description": "Cannot update, **User** record with specified ID **NOT** found"
-          },
-          "500": {
-            "description": "Internal server error"
-          }
-        },
-        "requestBody": {
-          "description": "JSON dictionary representing the User instance to update.",
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/user-without-required-constraint"
-              }
-            }
-          }
-        }
       }
     },
     "/user/{_id}/{association}/{childid}": {