Merge pull request #231 from vladbarosan/enhanceReadme

Enhance readme
Azure · Apr 6, 2018 · 783c9bb · 783c9bb
2 parents b83f50a + ff80fc4
commit 783c9bb
Show file tree

Hide file tree

Showing 2 changed files with 235 additions and 100 deletions.
diff --git a/README.md b/README.md
@@ -1,100 +1,120 @@
-# openapi-validation-tools [oav]
-Tools for validating OpenAPI (Swagger) files.
-
-### Requirements
-- **node.js version > 6.x**
-
-You can install the latest stable release of node.js from [here](https://nodejs.org/en/download/). For a machine with a linux flavored OS, please follow the node.js installation instructions over [here](https://nodejs.org/en/download/package-manager/)
-
-
-### How to install the tool 
-```
-npm install -g oav
-```
-
-#### Command usage:
-```
-bash-3.2$ oav -h
-Commands:
-  extract-xmsexamples <spec-path>           Extracts the x-ms-examples for a
-  <recordings>                              given swagger from the .NET session
-                                            recordings and saves them in a file.
-  generate-uml <spec-path>                  Generates a class diagram of the
-                                            model definitions in the given
-                                            swagger spec.
-  generate-wireformat <spec-path>           Transforms the x-ms-examples for a
-                                            given operation into raw
-                                            request/response format and saves
-                                            them in a markdown file.
-  resolve-spec <spec-path>                  Resolves the swagger spec based on
-                                            the selected options like allOfs,
-                                            relativePaths, examples etc.
-  validate-example <spec-path>              Performs validation of x-ms-examples
-                                            and examples present in the spec.
-  validate-spec <spec-path>                 Performs semantic validation of the
-                                            spec.
-
-Options:
-  --version          Show version number                               [boolean]
-  -l, --logLevel     Set the logging level for console.
-  [choices: "off", "json", "error", "warn", "info", "verbose", "debug", "silly"]
-                                                               [default: "warn"]
-  -f, --logFilepath  Set the log file path. It must be an absolute filepath. By
-                     default the logs will stored in a timestamp based log file
-                     at "C:\Users\amzavery\oav_output".
-  -h, --help         Show help                                         [boolean]
-
-bash-3.2$
-```
-
-### What does the tool do? What issues does the tool catch?
-
-Model validation checks whether definitions for request parameters and responses, match an expected input/output payload of the service.
-
-Examples of issues: 
-- required properties not sent in requests or responses; 
-- defined types not matching the value provided in the payload; 
-- constraints on properties not met; enumeration values that don’t match the value used by the service. 
-
-References: https://github.com/Azure/azure-rest-api-specs/issues/778 , https://github.com/Azure/azure-rest-api-specs/issues/755 , https://github.com/Azure/azure-rest-api-specs/issues/773 
-
-Model validation *requires* example payloads (request/response) of the service, so the data can be matched with the defined models. See [x-ms-examples extension](https://github.com/Azure/azure-rest-api-specs/issues/648) on how to specify the examples/payloads. Swagger “examples” is also supported and data included there is validated as well. To get the most benefit from this tool, make sure to have the simplest and most complex examples possible as part of x-ms-examples.
-The tool relies on swagger-tools package to perform model validation.
-
-- Please take a look at the redis-cache swagger spec as an example for providing "x-ms-examples" over [here](https://github.com/Azure/azure-rest-api-specs/blob/master/arm-redis/2016-04-01/swagger/redis.json#L45).
-- The examples need to be provided in a separate file in the examples directory under the api-version directory `azure-rest-api-specs/arm-<yourService>/<api-version>/examples/<exampleName>.json`. You can take a look over [here](https://github.com/Azure/azure-rest-api-specs/tree/master/arm-redis/2016-04-01/examples) for the structure of examples.
-- We require you to provide us a minimum (just required properties/parameters of the request/response) and a maximum (full blown) example. Feel free to provide more examples as deemed necessary. 
-- We have provided schemas for examples to be provided in the examples directory. It can be found over [here](https://github.com/Azure/autorest/blob/master/schema/example-schema.json). This will help you with intellisene and validation.
-  - If you are using **vscode** to edit your swaggers in the azure-rest-api-specs repo then everything should work out of the box as the schemas have been added in the `.vscode/settings.json` file over [here](https://github.com/Azure/azure-rest-api-specs/blob/master/.vscode/settings.json).
-  - If you are using **Visual Studio** then you can use the urls provided in the settings.json file and put them in the drop down list at the top of a json file when the file is opened in VS.
-
-### How does this tool fit with others?
-
-Swagger specs validation could be split in the following:
-   1.	Schema validation
-   2.	Semantic validation 
-   3.	Model definition validation
-   4.	Swagger operations execution (against mocked data or live tests)
-   5.	Human-eye review to complement the above
-
-In the context of “azure-rest-api-specs” repo:
-  - #1 is being performed on every PR as part of CI.
-  - #2 and #3 are performed by the tool currently in openapi-validation-tools repo and by AutoRest linter. We’re working towards integrating them into CI for “azure-rest-api-specs” repo.
-  -	#4 is not available yet, though we’re starting to work on it. 
-  -	#5 will be done by the approvers of PRs in “azure-rest-api-specs”, as this won’t be automated. 
-
-
-
-### Autorest plugin configuration
-- Please don't edit this section unless you're re-configuring how oav plugs in to AutoRest
-AutoRest needs the below config to pick this up as a plug-in - see https://github.com/Azure/autorest/blob/master/docs/developer/architecture/AutoRest-extension.md
-
-``` yaml $(model-validator)
-pipeline:
-  swagger-document/model-validator:
-    input: swagger-document/identity
-```
-
-
----
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+# openapi-validation-tools [oav]
+Tools for validating OpenAPI (Swagger) files.
+
+### Requirements
+- **node.js version > 6.x**
+
+You can install the latest stable release of node.js from [here](https://nodejs.org/en/download/). For a machine with a linux flavored OS, please follow the node.js installation instructions over [here](https://nodejs.org/en/download/package-manager/)
+
+
+### How to install the tool
+```
+npm install -g oav
+```
+
+#### Command usage:
+```
+bash-3.2$ oav -h
+Commands:
+  extract-xmsexamples <spec-path>           Extracts the x-ms-examples for a
+  <recordings>                              given swagger from the .NET session
+                                            recordings and saves them in a file.
+  generate-uml <spec-path>                  Generates a class diagram of the
+                                            model definitions in the given
+                                            swagger spec.
+  generate-wireformat <spec-path>           Transforms the x-ms-examples for a
+                                            given operation into raw
+                                            request/response format and saves
+                                            them in a markdown file.
+  resolve-spec <spec-path>                  Resolves the swagger spec based on
+                                            the selected options like allOfs,
+                                            relativePaths, examples etc.
+  validate-example <spec-path>              Performs validation of x-ms-examples
+                                            and examples present in the spec.
+  validate-spec <spec-path>                 Performs semantic validation of the
+                                            spec.
+
+Options:
+  --version          Show version number                               [boolean]
+  -l, --logLevel     Set the logging level for console.
+  [choices: "off", "json", "error", "warn", "info", "verbose", "debug", "silly"]
+                                                               [default: "warn"]
+  -f, --logFilepath  Set the log file path. It must be an absolute filepath. By
+                     default the logs will stored in a timestamp based log file
+                     at "C:\Users\amzavery\oav_output".
+  -h, --help         Show help                                         [boolean]
+
+bash-3.2$
+```
+
+### What does the tool do? What issues does the tool catch?
+
+Model validation checks whether definitions for request parameters and responses, match an expected input/output payload of the service.
+
+Examples of issues:
+- required properties not sent in requests or responses;
+- defined types not matching the value provided in the payload;
+- constraints on properties not met; enumeration values that don’t match the value used by the service.
+
+References: https://github.com/Azure/azure-rest-api-specs/issues/778 , https://github.com/Azure/azure-rest-api-specs/issues/755 , https://github.com/Azure/azure-rest-api-specs/issues/773
+
+Model validation *requires* example payloads (request/response) of the service, so the data can be matched with the defined models. See [x-ms-examples extension](https://github.com/Azure/azure-rest-api-specs/issues/648) on how to specify the examples/payloads. Swagger “examples” is also supported and data included there is validated as well. To get the most benefit from this tool, make sure to have the simplest and most complex examples possible as part of x-ms-examples.
+The tool relies on swagger-tools package to perform model validation.
+
+- Please take a look at the redis-cache swagger spec as an example for providing "x-ms-examples" over [here](https://github.com/Azure/azure-rest-api-specs/blob/master/arm-redis/2016-04-01/swagger/redis.json#L45).
+- The examples need to be provided in a separate file in the examples directory under the api-version directory `azure-rest-api-specs/arm-<yourService>/<api-version>/examples/<exampleName>.json`. You can take a look over [here](https://github.com/Azure/azure-rest-api-specs/tree/master/arm-redis/2016-04-01/examples) for the structure of examples.
+- We require you to provide us a minimum (just required properties/parameters of the request/response) and a maximum (full blown) example. Feel free to provide more examples as deemed necessary.
+- We have provided schemas for examples to be provided in the examples directory. It can be found over [here](https://github.com/Azure/autorest/blob/master/schema/example-schema.json). This will help you with intellisene and validation.
+  - If you are using **vscode** to edit your swaggers in the azure-rest-api-specs repo then everything should work out of the box as the schemas have been added in the `.vscode/settings.json` file over [here](https://github.com/Azure/azure-rest-api-specs/blob/master/.vscode/settings.json).
+  - If you are using **Visual Studio** then you can use the urls provided in the settings.json file and put them in the drop down list at the top of a json file when the file is opened in VS.
+
+### How does this tool fit with others?
+
+Swagger specs validation could be split in the following:
+   1.	Schema validation
+   2.	Semantic validation
+   3.	Model definition validation
+   4.	Swagger operations execution (against mocked data or live tests)
+   5.	Human-eye review to complement the above
+
+In the context of “azure-rest-api-specs” repo:
+  - #1 is being performed on every PR as part of CI.
+  - #2 and #3 are performed by the tool currently in openapi-validation-tools repo and by AutoRest linter. We’re working towards integrating them into CI for “azure-rest-api-specs” repo.
+  -	#4 is not available yet, though we’re starting to work on it.
+  -	#5 will be done by the approvers of PRs in “azure-rest-api-specs”, as this won’t be automated.
+
+
+
+### Autorest plugin configuration
+- Please don't edit this section unless you're re-configuring how oav plugs in to AutoRest
+AutoRest needs the below config to pick this up as a plug-in - see https://github.com/Azure/autorest/blob/master/docs/developer/architecture/AutoRest-extension.md
+
+``` yaml $(model-validator)
+pipeline:
+  swagger-document/model-validator:
+    input: swagger-document/identity
+```
+### Live Validation Mode
+- A **Live Validation** mode has been added to OAV with the purpose of enabling validation of live traffic.
+- Usage (here is a sample of a [request-response pair]()):
+```javascript
+  const liveValidatorOptions = {
+    git: {
+      url: "https://github.com/Azure/azure-rest-api-specs.git",
+      shouldClone: true
+    },
+    directory: path.resolve(os.homedir(), "cloneRepo"),
+    swaggerPathsPattern: "/specification/**/resource-manager/**/*.json",
+    isPathCaseSensitive: false,
+    shouldModelImplicitDefaultResponse: true
+  };
+
+  let apiValidator = new oav.LiveValidator(liveValidatorOptions);
+  await apiValidator.initialize(); // Note that for a large number of specs this can take some time.
+
+  // After `initialize()` finishes we are ready to validate
+  let validationResult = apiValidator.validateLiveRequestResponse(requestResponsePair);
+```
+
+---
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
diff --git a/test/sampleRequestResponsePair.json b/test/sampleRequestResponsePair.json
@@ -0,0 +1,115 @@
+{
+  "liveRequest": {
+    "body": {
+      "location": "SoutheastAsia",
+      "tags": {
+        "RG": "rg",
+        "testTag": "1"
+      },
+      "properties": {
+        "hardwareProfile": {
+          "vmSize": "Standard_A0"
+        },
+        "storageProfile": {
+          "imageReference": {
+            "publisher": "MicrosoftWindowsServer",
+            "offer": "WindowsServer",
+            "sku": "2012-R2-Datacenter",
+            "version": "4.0.201505"
+          },
+          "osDisk": {
+            "name": "test",
+            "vhd": {
+              "uri": "https://randomuri.blob.core.windows.net/pslibtest1846/ospslibtest7802.vhd"
+            },
+            "caching": "None",
+            "createOption": "fromImage"
+          }
+        },
+        "osProfile": {
+          "computerName": "test",
+          "adminUsername": "Foo12",
+          "adminPassword": "[PLACEHOLDER]",
+          "customData": "ZWNobyAnSGVsbG8gV29ybGQn",
+          "windowsConfiguration": {
+            "provisionVMAgent": true,
+            "enableAutomaticUpdates": false,
+            "timeZone": "Pacific Standard Time",
+            "additionalUnattendContent": [
+              {
+                "passName": "oobeSystem",
+                "componentName": "Microsoft-Windows-Shell-Setup",
+                "settingName": "AutoLogon",
+                "content": "<AutoLogon><Enabled>true</Enabled><LogonCount>5</LogonCount><Username>Foo12</Username><Password><Value>[PLACEHOLDER]</Value><PlainText>true</PlainText></Password></AutoLogon>"
+              }
+            ],
+            "winRM": {
+              "listeners": [
+                {
+                  "protocol": "Http"
+                },
+                {
+                  "protocol": "Https",
+                  "certificateUrl": "https://randomkeyvault.vault.azure.net/secrets/WinRM/24c727e7449b47cb9d2f385113f59a63"
+                }
+              ]
+            }
+          },
+          "secrets": [
+            {
+              "sourceVault": {
+                "id": "/subscriptions/sub1/resourceGroups/pslibtestosprofile/providers/Microsoft.KeyVault/vaults/pslibtestkeyvault"
+              },
+              "vaultCertificates": [
+                {
+                  "certificateUrl": "https://randomkeyvault.vault.azure.net/secrets/WinRM/24c727e7449b47cb9d2f385113f59a63",
+                  "certificateStore": "My"
+                }
+              ]
+            }
+          ]
+        },
+        "networkProfile": {
+          "networkInterfaces": [
+            {
+              "id": "/subscriptions/randomsub1/resourceGroups/pslibtest9279/providers/Microsoft.Network/networkInterfaces/azsmnet504"
+            }
+          ]
+        },
+        "availabilitySet": {
+          "id": "/subscriptions/randomsub1/resourceGroups/pslibtest9279/providers/Microsoft.Compute/availabilitySets/as9002"
+        }
+      }
+    },
+    "method": "PUT",
+    "url": "/subscriptions/randomsub1/resourceGroups/pslibtest9279/providers/Microsoft.Compute/virtualMachines/vm1827?api-version=2017-12-01",
+    "headers": {
+      "Content-Type": "application/json; charset=utf-8",
+      "Content-Length": "2687",
+      "x-ms-client-request-id": "random x-ms client id",
+      "accept-language": "en-US",
+      "User-Agent": "Microsoft.Azure.Management.Compute.ComputeManagementClient/9.0.0.0"
+    }
+  },
+  "liveResponse": {
+    "body": {
+      "error": {
+        "code": "LinkedAuthorizationFailed",
+        "message": "random message"
+      }
+    },
+    "statusCode": "403",
+    "headers": {
+      "Content-Length": "628",
+      "Content-Type": "application/json; charset=utf-8",
+      "Expires": "-1",
+      "Pragma": "no-cache",
+      "x-ms-failure-cause": "gateway",
+      "x-ms-correlation-request-id": "requestid",
+      "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+      "Connection": "close",
+      "Cache-Control": "no-cache",
+      "Date": "Wed, 05 Aug 2015 23:15:01 GMT"
+    }
+  }
+}