@ -342,7 +342,7 @@ You can describe all the [possible HTTP Response status codes](http://www.w3.org
- If **a schema is provided** for the negative response codes then this will have an impact on the return type of the generated method.
- For example: if a schema was provided for 200, and 400 was also described with a schema then,
- the **return type** would be the Common Ancestor of both the schemas. In most cases there is nothing common between a positive and a negative response code. Hence the return type will be an `Object`. Note:This may not be very helpful to the customer
- an exception ** will NOT be thrown for 400** and the generated method will deserialize the response body as per the schema of "400".
- an exception **will NOT be thrown for 400** and the generated method will deserialize the response body as per the schema of "400".
- any other negative response code will be treated as per the "default" response status code defined in the swagger for that operation.
- If **a schema is NOT provided** for the negative response codes then this will **NOT** have an impact on the return type of the generated method.
- For example: if a schema was provided for 200 and 404 was described as one of the responses. However, 404 does not have a schema. In this scenario,
@ -25,9 +25,9 @@ We request OpenAPI(Swagger) spec authoringbe assigned to engineers who have an
| Required parametersMUSTbe accurately labeled as"required": truein OpenAPI(Swagger) spec | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Read only parameters of the model propertiesMUSTbe labeled as"readOnly": truein OpenAPI(Swagger) spec | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Required parametersMUSTbe accurately labeled as"required": truein OpenAPI(Swagger) spec | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Required properties of a model definitionMUSTbe accurately labeled as"required": [ "propertyName1" ]in OpenAPI(Swagger) spec |Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Required properties of a model definitionMUSTbe accurately labeled as"required": [ "propertyName1" ]in OpenAPI(Swagger) spec |Error | | ARM and Data plane OpenAPI(Swagger) specs |
| An OpenAPI(Swagger) specMUST NOTdefine operations or properties or parameters for functionalities that are not currently supported by the service in the given api-version. The primary goal of the spec is that itMUSTcorrectly and completely represent the underlying REST API. For example,NetworkInterface.ipConfigurationsis described as a collection. However, it does not support adding more than one IP configuration | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| A collection model in OpenAPI(Swagger) specMUSTsupport adding more than one element to the collection | Error| | ARM and Data plane OpenAPI(Swagger) specs |
| A collection model in OpenAPI(Swagger) specMUSTsupport adding more than one element to the collection | Error| | ARM and Data plane OpenAPI(Swagger) specs |
| Operations that are exposed through private previewsMUST NOTbe described in thepublic GitHub repository. TheyMUSTbe described in theprivate GitHub repositoryinstead | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Parameters that are common to most of the operations (example: resourceGroupName)SHOULDbe defined in the global parameters section and theyMUSThave the extension"x-ms-parameter-location": "method"applied on them. This will make sure that they do not end up being properties on the generated client | Error | SDK Violation | ARM and Data plane OpenAPI(Swagger) specs |
| Each operation described in a OpenAPI(Swagger) specificationMUSTbe tested prior to opening a pull request against the preview/master branch of theAzure REST API SpecsGitHub repo | Error | | ARM and Data plane OpenAPI(Swagger) specs |
@ -12,10 +12,10 @@ This checklist is a current snapshot of requirements for developing Swagger spec
Today, there are tools available for validating a sizable portion of this checklist. Please install these tools on your development machine and use them to validate your Swaggers as you build them.
-[AutoRest OpenAPI Validator](https://github.com/Azure/autorest/blob/master/docs/user/command-line-interface.md#validation) – The OpenAPI validator (activated with `--azure-validator`) statically analyzes a Swagger for errors and violations of requirements outlined in the automated rules checklist. The validator should be run when Swaggers are created or updated. It will be continuously updated to validate newer requirements.
-[AutoRest OpenAPI Validator](https://github.com/Azure/autorest/blob/master/docs/user/command-line-interface.md#validation) – The OpenAPI validator (activated with `--azure-validator`) statically analyzes a Swagger for errors and violations of requirements outlined in the automated rules checklist. The validator should be run when Swaggers are created or updated. It will be continuously updated to validate newer requirements.
**NOTE**: This checkmark ( :white_check_mark: ) indicates that rule is covered by AutoRest validation tool.
-[Swagger Model Validator](https://github.com/Azure/openapi-validation-tools) - Model Validator validates models defined for body parameters and responses, and matches them against the expected input and output of an operation. To make this real, test examples are required to be specified in a Swagger for every operation defined in a Swagger. Test examples are integrated into a Swagger using the ["x-ms-examples"](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) extension, which will be used to test against the defined models. Sample test examples for this extension can be found in the [Redis Cache Swagger](https://github.com/Azure/azure-rest-api-specs/blob/master/arm-redis/2016-04-01/swagger/redis.json ).
-[Swagger Model Validator](https://github.com/Azure/openapi-validation-tools) - Model Validator validates models defined for body parameters and responses, and matches them against the expected input and output of an operation. To make this real, test examples are required to be specified in a Swagger for every operation defined in a Swagger. Test examples are integrated into a Swagger using the ["x-ms-examples"](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) extension, which will be used to test against the defined models. Sample test examples for this extension can be found in the [Redis Cache Swagger](https://github.com/Azure/azure-rest-api-specs/blob/master/arm-redis/2016-04-01/swagger/redis.json ).
The Azure Developer Experience team will continue to deliver rich tools to validate this checklist.
The underlying APIs are available to users who would like to write their own REST calls. These APIs would allow the user to accept the terms at a subscription, offer and SKU level. These apis are invoked in the context of azure subscription.