Add Documentation to reflect migrated internal wiki items (#998)

* add example-generation doc to the review. beginning to update the two error reference docs with the possible errors
* cross-compare of the full list versus what we have documented in the error set
* remove accidentally duplicated entry

documentation/example-generation.md

@@ -0,0 +1,123 @@
+# Using `oav` to generate examples for a `swagger` specification
+
+An example is a JSON file representing the payload of a rest API call, which includes both request information and response information. An example is required to provide for each operation defined in a swagger. `oav` provides a tool to _generate_ examples given an swagger specification and optional REST payloads.
+
+## Pre-requisite
+
+- `oav` installed. Reference the [base readme](../README.md) for a guide on how to install `oav`.
+- An operation example is based on the operation defined in a swagger specification. So, a valid swagger is the **pre-requisite** content. 
+
+## Generation Workflow
+
+![exampleGenWorkflow.png](./img/generate_example_workflow.png)
+
+A video of this process is [available for Microsoft employees.](https://msit.microsoftstream.com/embed/video/f7b90840-98dc-94b1-9e29-f1eba35174a9?autoplay=false&showinfo=true)
+
+## How to run the tool
+
+```bash
+oav generate-examples <spec-path>
+
+Params:
+  spec-path          the swagger spec file path
+
+Options:
+  --version                Show version number                         [boolean]
+  -l, --logLevel           Set the logging level for console.
+  [choices: "off", "json", "error", "warn", "info", "verbose", "debug", "silly"]
+                                                               [default: "info"]
+  -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
+                           "/home/raychen/oav_output".
+  -p, --pretty             Pretty print
+  -o, --operationId        operation id.                                [string]
+  --payload, --payloadDir  the directory path contains payload.         [string]
+  -c, --config             the readme config path.                      [string]
+  --tag, --tagName         the readme tag name.                         [string]
+  -h, --help               Show help                                   [boolean]
+```
+
+### Input
+
+| Input | Description |
+|---|---|
+| **Swagger file path** | Only supports one swagger file. |
+| **Swagger readme file path** | Once this value is provided the swagger file path is ignored. This will generate examples for multiple swaggers defined in a specific tag in readme.md. |
+| **Tag name in swagger readme file** | The tag name. This value has to be provided when readme file path is provided. |
+| **Payloads directory** | Optional input. |
+
+### Output
+
+The generated examples will be dropped at the `examples` sub folder of the folder of swagger file. 
+It will generate two types of examples, first type example called `{operationId}_MinimumSet_Gen.json` includes all required properties only and the other type example called `{operationId}_MaximumSet_Gen.json` includes full set of properties.
+
+### Option 1
+
+1. Users only provide the swagger file (or both readme file and tag) as input. 
+2. Example generator mock values base on the swagger definition. 
+3. Update swagger adding `x-ms-examples` to reference the generated examples.
+4. Validate examples against swagger.
+
+```bash
+# Note that the Azure/azure-rest-api-specs repo is cloned down prior to invocation
+
+# Example of the command to run against one swagger file: 
+oav generate-examples path/to/rest/repo/azure-rest-api-specs/specification/storage/resource-manager/Microsoft.SignalRService/stable/2020-05-01/signalr.json
+
+# Example of the command to run against readme file and tag: 
+oav generate-examples --tag=package-2019-06 --config=path/to/rest/repo/azure-rest-api-specs/specification/storage/resource-manager/readme.md
+```
+
+### Option 2
+
+1. Users provide both of the swagger file path and payloads directory path of the related operations as input.
+2. Example generator runs basic validation for the payloads against the swagger file.
+3. Then generate the examples base on the payloads.
+4. Update swagger adding `x-ms-examples` to reference the generated examples.
+5. Validate examples against swagger.
+
+```bash
+# Example of the command to run against one swagger file and provided payloads: 
+oav generate-examples path/to/rest/repo/azure-rest-api-specs/specification/storage/resource-manager/Microsoft.SignalRService/stable/2020-05-01/signalr.json --payloadDir=C:/payloads
+```
+
+## What's the format of input payloads
+
+Payload directory should contain sub folders named by `[RP_namespace]/[stable|preview]/[api-version]/[operationId]`, for example, `Microsoft.AppPlatform/stable/2020-07-01/SignalR_Get`. Put payload files named by status code under this correspondent folder of `operationId`.
+
+For example,
+```bash
+.
+└── SignalR_Get
+    └── 200.json
+└── SignalR_CreateOrUpdate
+    ├── 201.json
+    └── 202.json
+```
+
+Payload file should be a valid json file and contains `liveRequest` and `liveResponse`. 
+For example,
+```json
+{
+    "liveRequest": {
+        "headers": {},
+        "method": "PUT",
+        "url": "",
+        "body": {},
+        "query": {}
+    },
+    "liveResponse": {
+        "statusCode": "202",
+        "headers": {
+        },
+        "body": {}
+    }
+}
+```
+
+You can create the payload files by yourself or it can leverage ARM traffic directly, please contact vscswagger@microsoft.com to fetch the traffic payloads.
+
+## Support and questions
+
+Please email vscswagger@microsoft.com.

documentation/oav-model-errors-reference.md

@@ -1,4 +1,4 @@
-# OAV Errors Reference
+# OAV Errors Reference (Model Validation)
 
 This document includes further reference for errors reported by `oav` validate-example command.
 
@@ -26,6 +26,7 @@ Errors described below may apply in request or response, your result output will
 | [RESPONSE_SCHEMA_NOT_IN_SPEC](#RESPONSE_SCHEMA_NOT_IN_SPEC)                   |
 | [REQUIRED_PARAMETER_EXAMPLE_NOT_FOUND](#REQUIRED_PARAMETER_EXAMPLE_NOT_FOUND) |
 | [RESPONSE_STATUS_CODE_NOT_IN_SPEC](#RESPONSE_STATUS_CODE_NOT_IN_SPEC)         |
+| [RESPONSE_VALIDATION_ERROR](#RESPONSE_VALIDATION_ERROR)                       |
 
 ## Errors Descriptions
 
@@ -216,3 +217,16 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 **How to fix the issue**: Remove the status code from example that is not specificed in the spec, or check whether the status code should be added to the OpenAPI spec.
 
 Links: [Index](#index) | [Error descriptions](#error-descriptions)
+
+### <a name="RESPONSE_VALIDATION_ERROR" />RESPONSE_VALIDATION_ERROR
+
+**Severity** : 1
+
+**Message** : ound errors in validating the response with statusCode {} ...
+
+**Description**: Found errors when validate the response defined in example.
+
+**How to fix the issue**: See inner details for the violations and fix.
+
+Links: [Index](#index) | [Error descriptions](#error-descriptions)
+

documentation/oav-semantic-errors-reference.md

@@ -1,4 +1,4 @@
-# OAV Errors Reference #
+# OAV Errors Reference (Semantic Validation)
 
 This document includes further reference for errors reported by `oav` validate-spec command. 
 
@@ -13,21 +13,27 @@ Errors described below indicate semantically incorrect OpenAPI2.0 files.
 | Error Code |
 | --- |
 | [EQUIVALENT_PATH](#EQUIVALENT_PATH)	|
-| [OBJECT_MISSING_REQUIRED_PROPERTY_DEFINITION](#OBJECT_MISSING_REQUIRED_PROPERTY_DEFINITION)|
+| [OBJECT_MISSING_REQUIRED_PROPERTY_DEFINITION](#OBJECT_MISSING_REQUIRED_PROPERTY_DEFINITION) |
-|[EMPTY_PATH_PARAMETER_DECLARATION](#EMPTY_PATH_PARAMETER_DECLARATION) |
+| [EMPTY_PATH_PARAMETER_DECLARATION](#EMPTY_PATH_PARAMETER_DECLARATION) |
-| [DUPLICATE_OPERATIONID](#DUPLICATE_OPERATIONID)|
+| [DUPLICATE_OPERATIONID](#DUPLICATE_OPERATIONID) |
-| [MULTIPLE_BODY_PARAMETERS](#MULTIPLE_BODY_PARAMETERS)|
+| [MULTIPLE_BODY_PARAMETERS](#MULTIPLE_BODY_PARAMETERS) |
-| [INVALID_PARAMETER_COMBINATION](#INVALID_PARAMETER_COMBINATION)|
+| [INVALID_PARAMETER_COMBINATION](#INVALID_PARAMETER_COMBINATION) |
-|[MISSING_PATH_PARAMETER_DEFINITION](#MISSING_PATH_PARAMETER_DEFINITION)|
+| [MISSING_PATH_PARAMETER_DEFINITION](#MISSING_PATH_PARAMETER_DEFINITION) |
-|[MISSING_PATH_PARAMETER_DECLARATION](#MISSING_PATH_PARAMETER_DECLARATION)|
+| [MISSING_PATH_PARAMETER_DECLARATION](#MISSING_PATH_PARAMETER_DECLARATION) |
-|[UNRESOLVABLE_REFERENCE](#UNRESOLVABLE_REFERENCE)|
+| [UNRESOLVABLE_REFERENCE](#UNRESOLVABLE_REFERENCE)| 
-|[ANY_OF_MISSING](#ANY_OF_MISSING)|
+| [ANY_OF_MISSING](#ANY_OF_MISSING) |
-|[ONE_OF_MISSING](#ONE_OF_MISSING)|
+| [ONE_OF_MISSING](#ONE_OF_MISSING) |
-|[INVALID_REFERENCE](#INVALID_REFERENCE)|
+| [INVALID_REFERENCE](#INVALID_REFERENCE) |
-|[OBJECT_MISSING_REQUIRED_PROPERTY](#OBJECT_MISSING_REQUIRED_PROPERTY)|
+| [OBJECT_MISSING_REQUIRED_PROPERTY](#OBJECT_MISSING_REQUIRED_PROPERTY) |
-|[UNUSED_DEFINITION](#UNUSED_DEFINITION)|
+| [UNUSED_DEFINITION](#UNUSED_DEFINITION) |
-|[DUPLICATE_PARAMETER](#DUPLICATE_PARAMETER)|
+| [DUPLICATE_PARAMETER](#DUPLICATE_PARAMETER) |
-
+| [SEMANTIC_VALIDATION_ERROR](#DUPLICATE_PARAMETER) |
+| [X-MS-EXAMPLE_NOTFOUND_ERROR](#X-MS-EXAMPLE_NOTFOUND_ERROR) |
+| [SCHEMA_NOT_AN_OBJECT](#SCHEMA_NOT_AN_OBJECT) |
+| [SCHEMA_NOT_REACHABLE](#SCHEMA_NOT_REACHABLE) |
+| [SCHEMA_VALIDATION_FAILED](#SCHEMA_VALIDATION_FAILED) |
+| [UNRESOLVABLE_REFERENCE](#UNRESOLVABLE_REFERENCE) |
+| [UNKNOWN_FORMAT](#UNRESOLVABLE_REFERENCE) |
 
 ## Errors Descriptions
 
@@ -38,7 +44,7 @@ Errors from OAV validate-spec command will include:
 
 ### <a name="EQUIVALENT_PATH"/> EQUIVALENT_PATH 
 
-**Message** : Equivalent path already exists:  [path]
+**Message**: Equivalent path already exists:  [path]
 
 **Description**: Open API specification allows only unique paths.
 
@@ -48,7 +54,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="OBJECT_MISSING_REQUIRED_PROPERTY_DEFINITION" />OBJECT_MISSING_REQUIRED_PROPERTY_DEFINITION 
 
-**Message** : Missing required property definition: <property>
+**Message**: Missing required property definition: <property>
 
 **Description**: Property indicated as required for the operation is missing its definition.  
 
@@ -58,7 +64,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="EMPTY_PATH_PARAMETER_DECLARATION" />EMPTY_PATH_PARAMETER_DECLARATION 
 
-**Message** : Path parameter declaration cannot be empty: [parameter]
+**Message**: Path parameter declaration cannot be empty: [parameter]
 
 **Description**: Path paramater should be defined within the operation and not be empty.
 
@@ -68,7 +74,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="DUPLICATE_OPERATIONID" />DUPLICATE_OPERATIONID 
 
-**Message** : Cannot have multiple operations with the same operationId
+**Message**: Cannot have multiple operations with the same operationId
 
 **Description**: OperationIds must be unique within an OpenAPI specification.
 
@@ -78,7 +84,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="MULTIPLE_BODY_PARAMETERS" />MULTIPLE_BODY_PARAMETERS 
 
-**Message** : Operation cannot have multiple body parameters
+**Message**: Operation cannot have multiple body parameters
 
 **Description**: Only one body parameter is allowed per operation.
 
@@ -88,7 +94,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="INVALID_PARAMETER_COMBINATION" />INVALID_PARAMETER_COMBINATION 
 
-**Message** : Operation cannot have a body parameter and a formData parameter 
+**Message**: Operation cannot have a body parameter and a formData parameter 
 
 **Description**: Either body parameter or formData parameter are allowed per operation.
 
@@ -98,7 +104,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="MISSING_PATH_PARAMETER_DEFINITION" />MISSING_PATH_PARAMETER_DEFINITION 
 
-**Message** : Path parameter is declared but is not defined: [parameter]
+**Message**: Path parameter is declared but is not defined: [parameter]
 
 **Description**: Path parameter is included in path, but is not defined within the operation.
 
@@ -108,7 +114,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="MISSING_PATH_PARAMETER_DECLARATION" />MISSING_PATH_PARAMETER_DECLARATION 
 
-**Message** : Path parameter is defined but is not declared: [parameter]
+**Message**: Path parameter is defined but is not declared: [parameter]
 
 **Description**: There's a paramater defined as "in":"path", but not used/declared in the path of the operation.
 
@@ -118,7 +124,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="UNRESOLVABLE_REFERENCE" />UNRESOLVABLE_REFERENCE 
 
-**Message** : Reference could not be resolved: [ref]
+**Message**: Reference could not be resolved: [ref]
 
 **Description**: Reference cannot be resolved, path not found or file does not exist.
 
@@ -128,7 +134,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="ANY_OF_MISSING" />ANY_OF_MISSING 
 
-**Message** : Not a valid [def] definition.
+**Message**: Not a valid [def] definition.
 
 **Description**: OpenAPI structure is missing a section/keyword. 
 
@@ -138,7 +144,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="ONE_OF_MISSING" />ONE_OF_MISSING 
 
-**Message** : Not a valid [def] definition.
+**Message**: Not a valid [def] definition.
 
 **Description**: OpenAPI structure is missing a section/keyword. 
 
@@ -148,7 +154,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="INVALID_REFERENCE" />INVALID_REFERENCE 
 
-**Message** : Invalid JSON Reference | Specific error details.
+**Message**: Invalid JSON Reference | Specific error details.
 
 **Description**: Reference is invalid.
 
@@ -158,7 +164,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="OBJECT_MISSING_REQUIRED_PROPERTY" />OBJECT_MISSING_REQUIRED_PROPERTY 
 
-**Message** : Missing required property: [property]
+**Message**: Missing required property: [property]
 
 **Description**: Property marked as required is missing in the operation.
 
@@ -168,7 +174,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="UNUSED_DEFINITION" />UNUSED_DEFINITION 
 
-**Message** : Definition is not used: [definition].
+**Message**: Definition is not used: [definition].
 
 **Description**: Definition is not referenced/used in the file. 
 
@@ -178,7 +184,7 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 ### <a name="DUPLICATE_PARAMETER" />DUPLICATE_PARAMETER 
 
-**Message** : Operation cannot have duplicate parameters: [parameter]
+**Message**: Operation cannot have duplicate parameters: [parameter]
 
 **Description**: Parameters should be unique for the operation. 
 
@@ -186,4 +192,62 @@ Links: [Index](#index) | [Error descriptions](#error-descriptions)
 
 Links: [Index](#index) | [Error descriptions](#error-descriptions) 
 
+### <a name="X-MS-EXAMPLE_NOTFOUND_ERROR" />X-MS-EXAMPLE_NOTFOUND_ERROR
 
+**Message**: Operation cannot have duplicate parameters: [parameter]
+
+**Description**: Each operation should have example defined.
+
+**How to fix the issue**: Add `x-ms-example`` declaration for this operation.
+
+Links: [Index](#index) | [Error descriptions](#error-descriptions) 
+
+### <a name="SCHEMA_NOT_AN_OBJECT" />SCHEMA_NOT_AN_OBJECT
+
+**Message**: Schema is not an object: [parameter]
+
+**Description**: The schema type is expected to be object.
+
+**How to fix the issue**: Correct the schema type.
+
+Links: [Index](#index) | [Error descriptions](#error-descriptions) 
+
+### <a name="SCHEMA_NOT_REACHABLE" />SCHEMA_NOT_REACHABLE
+
+**Message**: Validator was not able to schema with uri: [parameter]
+
+**Description**: It fails to load the remote schema.
+
+**How to fix the issue**: Fix the uri of remote schema or network issue.
+
+Links: [Index](#index) | [Error descriptions](#error-descriptions) 
+
+### <a name="SCHEMA_VALIDATION_FAILED" />SCHEMA_VALIDATION_FAILED
+
+**Message**: Schema failed to validate against its parent schema, see inner errors for details.
+
+**Description**: The schema fails to validate against its parent schema.
+
+**How to fix the issue**: Fix the schema by comparing against parent schema.
+
+Links: [Index](#index) | [Error descriptions](#error-descriptions) 
+
+### <a name="UNRESOLVABLE_REFERENCE" />UNRESOLVABLE_REFERENCE
+
+**Message**: Reference could not be resolved: [parameter]
+
+**Description**: It fails to resolve the reference uri of a remote schema.
+
+**How to fix the issue**:  Fix the uri.
+
+Links: [Index](#index) | [Error descriptions](#error-descriptions) 
+
+### <a name="UNKNOWN_FORMAT" />UNKNOWN_FORMAT
+
+**Message**: There is no validation function for format: [parameter]
+
+**Description**: `oav` does not support format validation of this type.
+
+**How to fix the issue**: Use another format or file an issue against azure/oav.
+
+Links: [Index](#index) | [Error descriptions](#error-descriptions)