This commit is contained in:
Nick Schonning 2019-07-16 17:33:41 -04:00 коммит произвёл Yunge Zhu
Родитель 737110f8ed
Коммит cf3a9cdfaf
9 изменённых файлов: 82 добавлений и 55 удалений

27
.markdownlint.json Normal file
Просмотреть файл

@ -0,0 +1,27 @@
{
"default": true,
"MD001": false,
"MD003": false,
"MD004": false,
"MD005": false,
"MD006": false,
"MD007": false,
"MD009": false,
"MD012": false,
"MD013": false,
"MD020": false,
"MD022": false,
"MD024": false,
"MD025": false,
"MD026": false,
"MD028": false,
"MD029": false,
"MD031": false,
"MD032": false,
"MD033": false,
"MD034": false,
"MD036": false,
"MD040": false,
"MD041": false,
"MD047": false
}

Просмотреть файл

@ -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,

Просмотреть файл

@ -32,34 +32,34 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| Id | Rule Name | Applies to |
| --- | --- | --- |
| [R3012](#r3012) | [APIVersionPattern](#r3012) | ARM OpenAPI(swagger) specs |
| [R3019](#r3019) | [ARMResourcePropertiesBag](#r3019) | ARM and Data plane OpenAPI(swagger) specs |
| [R3014](#r3014) | [BodyPropertiesNamesCamelCase](#r3014) | ARM and Data plane OpenAPI(swagger) specs |
| [R3016](#r3016) | [DefinitionsPropertiesNamesCamelCase](#r3016) | ARM and Data plane OpenAPI(swagger) specs |
| [R3006](#r3006) | [BodyTopLevelProperties](#r3006) | ARM OpenAPI(swagger) specs |
| [R3008](#r3008) | [CollectionObjectPropertiesNaming](#r3008) | ARM and Data plane OpenAPI(swagger) specs |
| [R2044](#r2044) | [InvalidVerbUsed](#r2044) | ARM and Data plane OpenAPI(swagger) specs |
| [R3023](#r3023) | [OperationsAPIImplementation](#r3023) | ARM OpenAPI(swagger) specs |
| [R3007](#r3007) | [PutGetPatchResponseSchema](#r3007) | ARM and Data plane OpenAPI(swagger) specs |
| [R3025](#r3025) | [TrackedResourceGetOperation](#r3025) | ARM OpenAPI(swagger) specs |
| [R3026](#r3026) | [TrackedResourcePatchOperation](#r3026) | ARM OpenAPI(swagger) specs |
| [R2059](#r2059) | [UniqueResourcePaths](#r2059) | ARM OpenAPI(swagger) specs |
| [R2016](#r2016) | [PatchBodyParametersSchema](#r2016) | ARM and Data plane OpenAPI(swagger) specs |
| [R2062](#r2062) | [XmsResourceInPutResponse](#r2062) | ARM OpenAPI(swagger) specs |
| [R3027](#r3027) | [TrackedResourceListByResourceGroup](#r3027) | ARM OpenAPI(swagger) specs |
| [R3028](#r3028) | [TrackedResourceListBySubscription](#r3028) | ARM OpenAPI(swagger) specs |
| [R3011](#r3011) | [DescriptionMustNotBeNodeName](#r3011) | ARM and Data plane OpenAPI(swagger) specs |
| [R3012](#r3012) | [APIVersionPattern](#r3012) | ARM OpenAPI(swagger) specs |
| [R3019](#r3019) | [ARMResourcePropertiesBag](#r3019) | ARM and Data plane OpenAPI(swagger) specs |
| [R3014](#r3014) | [BodyPropertiesNamesCamelCase](#r3014) | ARM and Data plane OpenAPI(swagger) specs |
| [R3016](#r3016) | [DefinitionsPropertiesNamesCamelCase](#r3016) | ARM and Data plane OpenAPI(swagger) specs |
| [R3006](#r3006) | [BodyTopLevelProperties](#r3006) | ARM OpenAPI(swagger) specs |
| [R3008](#r3008) | [CollectionObjectPropertiesNaming](#r3008) | ARM and Data plane OpenAPI(swagger) specs |
| [R2044](#r2044) | [InvalidVerbUsed](#r2044) | ARM and Data plane OpenAPI(swagger) specs |
| [R3023](#r3023) | [OperationsAPIImplementation](#r3023) | ARM OpenAPI(swagger) specs |
| [R3007](#r3007) | [PutGetPatchResponseSchema](#r3007) | ARM and Data plane OpenAPI(swagger) specs |
| [R3025](#r3025) | [TrackedResourceGetOperation](#r3025) | ARM OpenAPI(swagger) specs |
| [R3026](#r3026) | [TrackedResourcePatchOperation](#r3026) | ARM OpenAPI(swagger) specs |
| [R2059](#r2059) | [UniqueResourcePaths](#r2059) | ARM OpenAPI(swagger) specs |
| [R2016](#r2016) | [PatchBodyParametersSchema](#r2016) | ARM and Data plane OpenAPI(swagger) specs |
| [R2062](#r2062) | [XmsResourceInPutResponse](#r2062) | ARM OpenAPI(swagger) specs |
| [R3027](#r3027) | [TrackedResourceListByResourceGroup](#r3027) | ARM OpenAPI(swagger) specs |
| [R3028](#r3028) | [TrackedResourceListBySubscription](#r3028) | ARM OpenAPI(swagger) specs |
| [R3011](#r3011) | [DescriptionMustNotBeNodeName](#r3011) | ARM and Data plane OpenAPI(swagger) specs |
| [R2020](#r2020) | [RequiredPropertiesMissingInResourceModel](#r2020) | ARM OpenAPI(swagger) specs |
#### ARM Warnings
| Id | Rule Name | Applies to |
| --- | --- | --- |
| [R3018](#r3018) | [EnumInsteadOfBoolean](#r3018) | ARM and Data plane OpenAPI(swagger) specs |
| [R3017](#r3017) | [GuidUsage](#r3017) | ARM and Data plane OpenAPI(swagger) specs |
| [R2057](#r2057) | [InvalidSkuModel](#r2057) | ARM OpenAPI(swagger) specs |
| [R3010](#r3010) | [TrackedResourceListByImmediateParent](#r3010) | ARM OpenAPI(swagger) specs |
| [R2004](#r2004) | [NonApplicationJsonType](#r2004) | ARM OpenAPI(swagger) specs |
| [R3018](#r3018) | [EnumInsteadOfBoolean](#r3018) | ARM and Data plane OpenAPI(swagger) specs |
| [R3017](#r3017) | [GuidUsage](#r3017) | ARM and Data plane OpenAPI(swagger) specs |
| [R2057](#r2057) | [InvalidSkuModel](#r2057) | ARM OpenAPI(swagger) specs |
| [R3010](#r3010) | [TrackedResourceListByImmediateParent](#r3010) | ARM OpenAPI(swagger) specs |
| [R2004](#r2004) | [NonApplicationJsonType](#r2004) | ARM OpenAPI(swagger) specs |
### SDK Violations
@ -69,26 +69,26 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| --- | --- | --- |
| [R2024](#r2024) | [AnonymousBodyParameter](#r2024) | ARM and Data plane OpenAPI(swagger) specs |
| [R2026](#r2026) | [AvoidAnonymousTypes](#r2026) | ARM and Data plane OpenAPI(swagger) specs |
| [R2014](#r2014) | [SubscriptionIdParameterInOperations](#r2014) | ARM and Data plane OpenAPI(swagger) specs |
| [R2027](#r2027) | [DefaultMustBeInEnum](#r2027) | ARM and Data plane OpenAPI(swagger) specs |
| [R1001](#r1001) | [OperationIdNounInVerb](#r1001) | ARM and Data plane OpenAPI(swagger) specs |
| [R2055](#r2055) | [OneUnderscoreInOperationId](#r2055) | ARM and Data plane OpenAPI(swagger) specs |
| [R2003](#r2003) | [ValidFormats](#r2003) | ARM and Data plane OpenAPI(swagger) specs |
| [R2005](#r2005) | [LongRunningResponseStatusCode](#r2005) | ARM and Data plane OpenAPI(swagger) specs |
| [R2008](#r2008) | [MutabilityWithReadOnlyRule](#r2008) | ARM and Data plane OpenAPI(swagger) specs |
| [R2025](#r2025) | [NextLinkPropertyMustExist](#r2025) | ARM and Data plane OpenAPI(swagger) specs |
| [R2014](#r2014) | [SubscriptionIdParameterInOperations](#r2014) | ARM and Data plane OpenAPI(swagger) specs |
| [R2027](#r2027) | [DefaultMustBeInEnum](#r2027) | ARM and Data plane OpenAPI(swagger) specs |
| [R1001](#r1001) | [OperationIdNounInVerb](#r1001) | ARM and Data plane OpenAPI(swagger) specs |
| [R2055](#r2055) | [OneUnderscoreInOperationId](#r2055) | ARM and Data plane OpenAPI(swagger) specs |
| [R2003](#r2003) | [ValidFormats](#r2003) | ARM and Data plane OpenAPI(swagger) specs |
| [R2005](#r2005) | [LongRunningResponseStatusCode](#r2005) | ARM and Data plane OpenAPI(swagger) specs |
| [R2008](#r2008) | [MutabilityWithReadOnlyRule](#r2008) | ARM and Data plane OpenAPI(swagger) specs |
| [R2025](#r2025) | [NextLinkPropertyMustExist](#r2025) | ARM and Data plane OpenAPI(swagger) specs |
| [R2028](#r2028) | [NonEmptyClientName](#r2028) | ARM and Data plane OpenAPI(swagger) specs |
| [R2060](#r2060) | [PageableRequires200Response](#r2060) | ARM and Data plane OpenAPI(swagger) specs |
| [R2019](#r2019) | [ResourceHasXMsResourceEnabled](#r2019) | ARM OpenAPI(swagger) specs |
| [R2019](#r2019) | [ResourceHasXMsResourceEnabled](#r2019) | ARM OpenAPI(swagger) specs |
| [R2058](#r2058) | [XmsPathsMustOverloadPaths](#r2058) | ARM and Data plane OpenAPI(swagger) specs |
| [R2012](#r2012) | [XmsClientNameParameter](#r2012) | ARM and Data plane OpenAPI(swagger) specs |
| [R2013](#r2013) | [XmsClientNameProperty](#r2013) | ARM and Data plane OpenAPI(swagger) specs |
| [R2047](#r2047) | [NamePropertyDefinitionInParameter](#r2047) | ARM and Data plane OpenAPI(swagger) specs |
| [R2056](#r2056) | [RequiredReadOnlyProperties](#r2056) | ARM and Data plane OpenAPI(swagger) specs |
| [R2054](#r2054) | [SecurityDefinitionsStructure](#r2054) | ARM OpenAPI(swagger) specs |
| [R2006](#r2006) | [ControlCharactersNotAllowed](#r2006) | ARM and Data plane OpenAPI(swagger) specs |
| [R2009](#r2009) | [ArraySchemaMustHaveItems](#r2009) | ARM and Data plane OpenAPI(swagger) specs |
| [R3013](#r3013) | [DeleteMustNotHaveRequestBody](#r3013) | ARM and Data plane OpenAPI(swagger) specs |
| [R2012](#r2012) | [XmsClientNameParameter](#r2012) | ARM and Data plane OpenAPI(swagger) specs |
| [R2013](#r2013) | [XmsClientNameProperty](#r2013) | ARM and Data plane OpenAPI(swagger) specs |
| [R2047](#r2047) | [NamePropertyDefinitionInParameter](#r2047) | ARM and Data plane OpenAPI(swagger) specs |
| [R2056](#r2056) | [RequiredReadOnlyProperties](#r2056) | ARM and Data plane OpenAPI(swagger) specs |
| [R2054](#r2054) | [SecurityDefinitionsStructure](#r2054) | ARM OpenAPI(swagger) specs |
| [R2006](#r2006) | [ControlCharactersNotAllowed](#r2006) | ARM and Data plane OpenAPI(swagger) specs |
| [R2009](#r2009) | [ArraySchemaMustHaveItems](#r2009) | ARM and Data plane OpenAPI(swagger) specs |
| [R3013](#r3013) | [DeleteMustNotHaveRequestBody](#r3013) | ARM and Data plane OpenAPI(swagger) specs |
| [R4001](#r4001) | [XmsParameterLocation](#r4001) | ARM and Data plan OpenAPI(swagger) specs |
#### SDK Warnings
@ -99,16 +99,16 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| [R4000](#r4000-3) | [DescriptiveDescriptionRequired](#r4000-3) | ARM and Data plane OpenAPI(swagger) specs |
| [R4000](#r4000-4) | [DescriptionAndTitleMissing](#r4000-4) | ARM and Data plane OpenAPI(swagger) specs |
| [R4000](#r4000-5) | [OperationDescriptionOrSummaryRequired](#r4000-5) | ARM and Data plane OpenAPI(swagger) specs |
| [R2001](#r2001) | [AvoidNestedProperties](#r2001) | ARM and Data plane OpenAPI(swagger) specs |
| [R4002](#r4002) | [LocationMustHaveXmsMutability](#r4002) | ARM OpenAPI(swagger) specs |
| [R2066](#r2066) | [PostOperationIdContainsUrlVerb](#r2066) | ARM and Data plane OpenAPI(swagger) specs |
| [R2001](#r2001) | [AvoidNestedProperties](#r2001) | ARM and Data plane OpenAPI(swagger) specs |
| [R4002](#r4002) | [LocationMustHaveXmsMutability](#r4002) | ARM OpenAPI(swagger) specs |
| [R2066](#r2066) | [PostOperationIdContainsUrlVerb](#r2066) | ARM and Data plane OpenAPI(swagger) specs |
| [R2015](#r2015) | [ParameterNotDefinedInGlobalParameters](#r2015) | ARM and Data plane OpenAPI(swagger) specs |
| [R1010](#r1010) | [AvoidMSDNReferences](#r1010) | ARM and Data plane OpenAPI(swagger) specs |
| [R2017](#r2017) | [PutRequestResponseScheme](#r2017) | ARM and Data plane OpenAPI(swagger) specs |
| [R2017](#r2017) | [PutRequestResponseScheme](#r2017) | ARM and Data plane OpenAPI(swagger) specs |
| [R1009](#r1009) | [DeleteInOperationName](#r1009) | ARM and Data plane OpenAPI(swagger) specs |
| [R1005](#r1005) | [GetInOperationName](#r1005) | ARM and Data plane OpenAPI(swagger) specs |
| [R1003](#r1003) | [ListInOperationName](#r1003) | ARM and Data plane OpenAPI(swagger) specs |
| [R1006](#r1006) | [PutInOperationName](#r1006) | ARM and Data plane OpenAPI(swagger) specs |
| [R1006](#r1006) | [PutInOperationName](#r1006) | ARM and Data plane OpenAPI(swagger) specs |
| [R1007](#r1007) | [PatchInOperationName](#r1007) | ARM and Data plane OpenAPI(swagger) specs |
| [R1011](#r1011) | [HttpsSupportedScheme](#r1011) | ARM OpenAPI(swagger) specs |
| [R2065](#r2065) | [LicenseHeaderMustNotBeSpecified](#r2065) | ARM and Data plane OpenAPI(swagger) specs |
@ -331,7 +331,7 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul
Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rules](#automated-rules) | [ARM](#arm-violations): [Errors](#arm-errors) or [Warnings](#arm-warnings) | [SDK](#sdk-violations): [Errors](#sdk-errors) or [Warnings](#sdk-warnings)
### <a name="r4002" />R4002 LocationMustHaveXmsMutability
### <a name="r4002" />R4002 LocationMustHaveXmsMutability
**Category** : SDK Warning
**Applies to** : ARM OpenAPI(swagger) specs
@ -378,7 +378,7 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul
Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rules](#automated-rules) | [ARM](#arm-violations): [Errors](#arm-errors) or [Warnings](#arm-warnings) | [SDK](#sdk-violations): [Errors](#sdk-errors) or [Warnings](#sdk-warnings)
### <a name="r2066" />R2066 PostOperationIdContainsUrlVerb
### <a name="r2066" />R2066 PostOperationIdContainsUrlVerb
**Category** : SDK Warning
**Applies to** : ARM and Data plane OpenAPI(swagger) specs

Просмотреть файл

@ -25,9 +25,9 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| Required parameters MUST be accurately labeled as "required": true in OpenAPI(Swagger) spec | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Read only parameters of the model properties MUST be labeled as "readOnly": true in OpenAPI(Swagger) spec | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Required parameters MUST be accurately labeled as "required": true in OpenAPI(Swagger) spec | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Required properties of a model definition MUST be accurately labeled as "required": [ "propertyName1" ] in OpenAPI(Swagger) spec | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Required properties of a model definition MUST be accurately labeled as "required": [ "propertyName1" ] in OpenAPI(Swagger) spec | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| An OpenAPI(Swagger) spec MUST NOT define 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 it MUST correctly and completely represent the underlying REST API. For example, NetworkInterface.ipConfigurations is 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) spec MUST support adding more than one element to the collection | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| A collection model in OpenAPI(Swagger) spec MUST support adding more than one element to the collection | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Operations that are exposed through private previews MUST NOT be described in the public GitHub repository. They MUST be described in the private GitHub repository instead | Error | | ARM and Data plane OpenAPI(Swagger) specs |
| Parameters that are common to most of the operations (example: resourceGroupName) SHOULD be defined in the global parameters section and they MUST have 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) specification MUST be tested prior to opening a pull request against the preview/master branch of the Azure REST API Specs GitHub 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.

Просмотреть файл

@ -98,7 +98,7 @@ batch:
- tag: package-policy-2015-10-01-preview
```
### Profile: hybrid_2019_03_01
### Profile: hybrid_2019_03_01
These settings apply only when `--csharp-profile=hybrid_2019_03_01` is specified on the command line.

Просмотреть файл

@ -6,7 +6,7 @@ Feedback:
---------
1. [dsgouda] Mark user non-editable properties as Readonly
related discussion: https://github.com/Azure/azure-rest-api-specs/pull/6042#discussion_r289147638
related discussion: https://github.com/Azure/azure-rest-api-specs/pull/6042#discussion_r289147638
reference: https://github.com/Azure/azure-rest-api-specs/blob/master/specification/cognitiveservices/data-plane/LocalSearch/stable/v1.0/LocalSearch.json#L241

Просмотреть файл

@ -127,7 +127,7 @@ input-file:
- $.definitions.IdentityTokenResponse.properties.client_id
- $.definitions.IdentityTokenResponse.properties.object_id
- $.definitions.IdentityTokenResponse.properties.msi_res_id
- $.definitions.IdentityErrorResponse.properties.error_description
- $.definitions.IdentityErrorResponse.properties.error_description
```
---

Просмотреть файл

@ -4,7 +4,7 @@
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.
----
---
***GetAzureRmMarketplaceTerms***
**Request**