Add option to model implicit default response

.vscode/launch.json

@@ -83,6 +83,7 @@
       "cwd": "${workspaceRoot}",
       "stopOnEntry": false,
       "args": [
+        "--no-timeouts",
         "test/modelValidatorTests.js"
       ],
       "env": {}

ChangeLog.md

@@ -1,6 +1,10 @@
+### 03/15/2018 0.4.35
+- Validate default responses. [#228](https://github.com/Azure/oav/issues/228)
+- Add option to model an implicit default cloud error response. [#224](https://github.com/Azure/oav/issues/224)
+
 ### 03/08/2018 0.4.34
 - Updating default output level to info.
-- Fixing issue #225, where output verbosity wasn't respected in one case. 
+- Fixing issue #225, where output verbosity wasn't respected in one case.
 
 ### 02/28/2018 0.4.33
 - Don't validate pure objects.

lib/util/utils.js

@@ -758,3 +758,62 @@ function isPropertyRequired(propName, model) {
  * Contains the reverse mapping of http.STATUS_CODES
  */
 exports.statusCodeStringToStatusCode = lodash.invert(lodash.mapValues(http.STATUS_CODES, value => { return value.replace(/ |-/g, "").toLowerCase(); }));
+
+/**
+ * Models an ARM cloud error schema.
+ */
+exports.CloudErrorSchema = {
+  description: "Error response describing why the operation failed.",
+  schema: {
+    "$ref": "#/definitions/CloudErrorWrapper"
+  }
+};
+
+/**
+ * Models an ARM cloud error wrapper.
+ */
+exports.CloudErrorWrapper = {
+  type: "object",
+  properties: {
+    error: {
+      "$ref": "#/definitions/CloudError"
+    }
+  },
+  additionalProperties: false
+};
+
+/**
+ * Models a Cloud Error
+ */
+exports.CloudError = {
+  type: "object",
+  properties: {
+    code: {
+      type: "string",
+      description: "An identifier for the error. Codes are invariant and are intended to be consumed programmatically."
+    },
+    message: {
+      type: "string",
+      description: "A message describing the error, intended to be suitable for display in a user interface."
+    },
+    target: {
+      type: "string",
+      description: "The target of the particular error. For example, the name of the property in error."
+    },
+    details: {
+      type: "array",
+      items: { type: "object" },
+      description: "A list of additional details about the error."
+    },
+    additionalInfo: {
+      type: "array",
+      items: { type: "object" },
+      description: "A list of additional info about an error."
+    },
+    innererror: {
+      type: "object"
+    }
+  },
+  required: ["code", "message"],
+  additionalProperties: false
+};

lib/validators/liveValidator.js

@@ -41,6 +41,8 @@ class LiveValidator {
    *
    * @param {string} [options.directory] The directory where to clone github repository or from where to find swaggers. Defaults to "repo" under user directory.
    *
+   * @param {string} [options.shouldModelImplicitDefaultResponse] Specifies if to model a default response for operations even if it is not specified in the specs.
+   *
    * @returns {object} CacheBuilder Returns the configured CacheBuilder object.
    */
   constructor(options) {
@@ -141,7 +143,14 @@ class LiveValidator {
       return () => {
         log.info(`Building cache from: "${swaggerPath}"`);
 
-        let validator = new SpecValidator(swaggerPath, null, { isPathCaseSensitive: this.options.isPathCaseSensitive });
+        let validator = new SpecValidator(
+          swaggerPath,
+          null,
+          {
+            shouldModelImplicitDefaultResponse: this.options.shouldModelImplicitDefaultResponse,
+            isPathCaseSensitive: this.options.isPathCaseSensitive
+          });
+
         return validator.initialize().then((api) => {
           let operations = api.getOperations();
           let apiVersion = api.info.version.toLowerCase();

lib/validators/specResolver.js

@@ -47,6 +47,8 @@ class SpecResolver {
    *
    * @param {object} [options.shouldResolveNullableTypes] Should we allow null values to match any type? Default: true
    *
+   * @param {object} [options.shouldModelImplicitDefaultResponse] Should we model a default response even if it is not defined? Default: false
+   *
    * @return {object} An instance of the SpecResolver class.
    */
   constructor(specPath, specInJson, options) {
@@ -93,6 +95,9 @@ class SpecResolver {
     if (options.shouldResolveNullableTypes === null || options.shouldResolveNullableTypes === undefined) {
       options.shouldResolveNullableTypes = options.shouldResolveAllOf;
     }
+    if (options.shouldModelImplicitDefaultResponse === null || options.shouldModelImplicitDefaultResponse === undefined) {
+      options.shouldModelImplicitDefaultResponse = false;
+    }
     this.options = options;
   }
 
@@ -169,7 +174,13 @@ class SpecResolver {
       } else {
         return Promise.resolve(self);
       }
-    }).catch(function (err) {
+    }).then(() => {
+      if (self.options.shouldModelImplicitDefaultResponse) {
+        return self.modelImplicitDefaultResponse();
+      } else {
+        return Promise.resolve(self);
+      }
+    }).catch((err) => {
       let e = {
         message: `An Error occurred while resolving relative references and allOf in model definitions in the swagger spec: "${self.specPath}".`,
         code: ErrorCodes.ResolveSpecError.name,
@@ -216,9 +227,9 @@ class SpecResolver {
     }
 
     let allRefsRemoteRelative = JsonRefs.findRefs(doc, options);
-    let promiseFactories = utils.getKeys(allRefsRemoteRelative).map(function (refName) {
+    let promiseFactories = utils.getKeys(allRefsRemoteRelative).map((refName) => {
       let refDetails = allRefsRemoteRelative[refName];
-      return function () { return self.resolveRelativeReference(refName, refDetails, doc, docPath); };
+      return () => { return self.resolveRelativeReference(refName, refDetails, doc, docPath); };
     });
     if (promiseFactories.length) {
       return utils.executePromisesSequentially(promiseFactories);
@@ -271,7 +282,7 @@ class SpecResolver {
       docPath = utils.joinPath(docDir, parsedReference.filePath);
     }
 
-    return utils.parseJson(docPath).then(function (result) {
+    return utils.parseJson(docPath).then((result) => {
       if (!parsedReference.localReference) {
         //Since there is no local reference we will replace the key in the object with the parsed
         //json (relative) file it is refering to.
@@ -344,7 +355,7 @@ class SpecResolver {
     let spec = self.specInJson;
     let definitions = spec.definitions;
     let modelNames = utils.getKeys(definitions);
-    modelNames.map(function (modelName) {
+    modelNames.map((modelName) => {
       let model = definitions[modelName];
       let modelRef = '/definitions/' + modelName;
       return self.resolveAllOfInModel(model, modelRef);
@@ -370,7 +381,7 @@ class SpecResolver {
 
     if (!self.resolvedAllOfModels[modelRef]) {
       if (model && model.allOf) {
-        model.allOf.map(function (item) {
+        model.allOf.map((item) => {
           let referencedModel = item;
           let ref = item['$ref'];
           let slicedRef = ref ? ref.slice(1) : undefined;
@@ -435,7 +446,7 @@ class SpecResolver {
     let spec = self.specInJson;
     let definitions = spec.definitions;
     let modelNames = utils.getKeys(definitions);
-    modelNames.map(function (modelName) {
+    modelNames.map((modelName) => {
       if (definitions[modelName].allOf) {
         delete definitions[modelName].allOf;
       }
@@ -460,7 +471,7 @@ class SpecResolver {
     if (!modelNames) {
       modelNames = utils.getKeys(definitions);
     }
-    modelNames.forEach(function iterator(modelName) {
+    modelNames.forEach(modelName => {
       let model = definitions[modelName];
       if (model) {
         if (force || (!model.additionalProperties && (!(!model.properties || (model.properties && utils.getKeys(model.properties).length === 0))))) {
@@ -590,6 +601,26 @@ class SpecResolver {
     return Promise.resolve(self);
   }
 
+  /**
+   * Models a default response as a Cloud Error if none is specified in the api spec.
+   */
+  modelImplicitDefaultResponse() {
+    let self = this;
+    let spec = self.specInJson;
+    if (!spec.definitions.CloudError) {
+      spec.definitions.CloudErrorWrapper = utils.CloudErrorWrapper;
+      spec.definitions.CloudError = utils.CloudError;
+    }
+    for (let pathObj of utils.getValues(spec.paths)) {
+      for (let operation of utils.getValues(pathObj)) {
+
+        if (operation.responses && !operation.responses.default) {
+          operation.responses.default = utils.CloudErrorSchema;
+        }
+      }
+    }
+  }
+
   /**
    * Resolves the discriminator by replacing all the references to the parent model with a oneOf array containing
    * references to the parent model and all its child models. It also modifies the discriminator property in