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
This commit is contained in:
Scott Beddall
GitHub
Родитель
31a8314064
Коммит
61fe0ba253
|
|
@ -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
|
||||
|
||||
|
||||
|
||||
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.
|
||||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 17 KiB |
|
|
@ -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)
|
||||
|
||||
|
|
@ -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)|
|
||||
|[EMPTY_PATH_PARAMETER_DECLARATION](#EMPTY_PATH_PARAMETER_DECLARATION) |
|
||||
| [DUPLICATE_OPERATIONID](#DUPLICATE_OPERATIONID)|
|
||||
| [MULTIPLE_BODY_PARAMETERS](#MULTIPLE_BODY_PARAMETERS)|
|
||||
| [INVALID_PARAMETER_COMBINATION](#INVALID_PARAMETER_COMBINATION)|
|
||||
|[MISSING_PATH_PARAMETER_DEFINITION](#MISSING_PATH_PARAMETER_DEFINITION)|
|
||||
|[MISSING_PATH_PARAMETER_DECLARATION](#MISSING_PATH_PARAMETER_DECLARATION)|
|
||||
|[UNRESOLVABLE_REFERENCE](#UNRESOLVABLE_REFERENCE)|
|
||||
|[ANY_OF_MISSING](#ANY_OF_MISSING)|
|
||||
|[ONE_OF_MISSING](#ONE_OF_MISSING)|
|
||||
|[INVALID_REFERENCE](#INVALID_REFERENCE)|
|
||||
|[OBJECT_MISSING_REQUIRED_PROPERTY](#OBJECT_MISSING_REQUIRED_PROPERTY)|
|
||||
|[UNUSED_DEFINITION](#UNUSED_DEFINITION)|
|
||||
|[DUPLICATE_PARAMETER](#DUPLICATE_PARAMETER)|
|
||||
|
||||
| [OBJECT_MISSING_REQUIRED_PROPERTY_DEFINITION](#OBJECT_MISSING_REQUIRED_PROPERTY_DEFINITION) |
|
||||
| [EMPTY_PATH_PARAMETER_DECLARATION](#EMPTY_PATH_PARAMETER_DECLARATION) |
|
||||
| [DUPLICATE_OPERATIONID](#DUPLICATE_OPERATIONID) |
|
||||
| [MULTIPLE_BODY_PARAMETERS](#MULTIPLE_BODY_PARAMETERS) |
|
||||
| [INVALID_PARAMETER_COMBINATION](#INVALID_PARAMETER_COMBINATION) |
|
||||
| [MISSING_PATH_PARAMETER_DEFINITION](#MISSING_PATH_PARAMETER_DEFINITION) |
|
||||
| [MISSING_PATH_PARAMETER_DECLARATION](#MISSING_PATH_PARAMETER_DECLARATION) |
|
||||
| [UNRESOLVABLE_REFERENCE](#UNRESOLVABLE_REFERENCE)|
|
||||
| [ANY_OF_MISSING](#ANY_OF_MISSING) |
|
||||
| [ONE_OF_MISSING](#ONE_OF_MISSING) |
|
||||
| [INVALID_REFERENCE](#INVALID_REFERENCE) |
|
||||
| [OBJECT_MISSING_REQUIRED_PROPERTY](#OBJECT_MISSING_REQUIRED_PROPERTY) |
|
||||
| [UNUSED_DEFINITION](#UNUSED_DEFINITION) |
|
||||
| [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)
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче