Skip to content

Commit fd13a53

Browse files
veronicaggdsgouda
authored andcommitted
removing ParameterizedProperties doc, updating NonApplicationJson (#1504)
1 parent d932de9 commit fd13a53

File tree

1 file changed

+4
-47
lines changed

1 file changed

+4
-47
lines changed

documentation/openapi-authoring-automated-guidelines.md

Lines changed: 4 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
5757
| [R3017](#R3017) | [GuidUsage](#R3017) |
5858
| [R2057](#R2057) | [InvalidSkuModel](#R2057) |
5959
| [R3010](#R3010) | [TrackedResourceListByImmediateParent](#R3010) |
60-
| [R2061](#R2061) | [ParameterizeProperties](#R2061) |
60+
| [R2004](#R2004) | [NonApplicationJsonType](#R2004) |
6161

6262
### SDK Violations
6363

@@ -102,7 +102,6 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
102102
| [R2066](#R2066) | [PostOperationIdContainsUrlVerb](#R2066) |
103103
| [R2015](#R2015) | [ParameterNotDefinedInGlobalParameters](#R2015) |
104104
| [R1010](#R1010) | [AvoidMSDNReferences](#R1010) |
105-
| [R2004](#R2004) | [NonApplicationJsonType](#R2004) |
106105
| [R2017](#R2017) | [PutRequestResponseScheme](#R2017) |
107106
| [R1009](#R1009) | [DeleteInOperationName](#R1009) |
108107
| [R1005](#R1005) | [GetInOperationName](#R1005) |
@@ -587,15 +586,13 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul
587586
Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rules](#automated-rules) | [RPC](#rpc-violations): [Errors](#rpc-errors) or [Warnings](#rpc-warnings) | [SDK](#sdk-violations): [Errors](#sdk-errors) or [Warnings](#sdk-warnings)
588587

589588
### <a name="R2004" />R2004 NonApplicationJsonType
590-
**Output Message**: Please make sure that media types other than 'application/json' are supported by your service.
589+
**Output Message**: Only content-type 'application/json' is supported by ARM..
591590

592591
**Description**: Verifies whether operation supports "application/json" as consumes or produces section.
593592

594-
**Why the rule is important**: Per the ARM SDK guidelines, the AutoRest is used to generated the language SDKs. All the supported language generator currently handles "application/json" but some SDKs may support other content-types. This rule is in place to warn the swagger writter that not all the SDKs would work with other content-types.
593+
**Why the rule is important**: Per [ARM SDK guidelines](https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/common-api-details.md#client-request-headers) only content-type 'application/json' is supported.
595594

596-
**How to fix the violation**: Please consult with AutoRest to ensure that the content type desired can be supported.
597-
598-
**Impact on generated code**: If the other than `application/json` type is provided, not all SDKs would support that content-type.
595+
**How to fix the violation**: Make sure to include only 'application/json' in the spec consumes/produces. Make sure your service supports 'application/json'.
599596

600597
**Examples**: N/A
601598

@@ -1266,46 +1263,6 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul
12661263

12671264
Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rules](#automated-rules) | [RPC](#rpc-violations): [Errors](#rpc-errors) or [Warnings](#rpc-warnings) | [SDK](#sdk-violations): [Errors](#sdk-errors) or [Warnings](#sdk-warnings)
12681265

1269-
### <a name="R2061" />R2061 ParameterizeProperties
1270-
**Output Message**: Type values \"{0}\" have default value(s), please consider parameterizing them
1271-
1272-
**Description**: Path URLs must be of the form `/subscriptions/{subscriptionId}/providers/<ProviderName>/typename/{typevalue}`, i.e., typevalues must be parameterized.
1273-
1274-
**Why the rule is important**: Path URLs should follow a consistent pattern across RPs. Consistent URL patterns also ensure determination of a resource from the URL and in turn trigger other resource related rules.
1275-
1276-
**How to fix the violation**: Parameterize all type values as path parameters.
1277-
1278-
**Bad Examples**:
1279-
```
1280-
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/sampleAccount":{
1281-
1282-
}
1283-
```
1284-
**Good Examples**:
1285-
```
1286-
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}":{
1287-
"get":{
1288-
"parameters": [
1289-
{
1290-
"$ref": "#/parameters/ResourceGroupName"
1291-
},
1292-
{
1293-
"name": "accountName",
1294-
"in": "path",
1295-
"required": true,
1296-
"type": "string",
1297-
"description": "The name of the storage account within the specified resource group. Storage account names must be between 3 and 24 characters in length and use numbers and lower-case letters only.",
1298-
"maxLength": 24,
1299-
"minLength": 3
1300-
},
1301-
...
1302-
1303-
}
1304-
}
1305-
```
1306-
1307-
Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rules](#automated-rules) | [RPC](#rpc-violations): [Errors](#rpc-errors) or [Warnings](#rpc-warnings) | [SDK](#sdk-violations): [Errors](#sdk-errors) or [Warnings](#sdk-warnings)
1308-
13091266
### <a name="R2063" />R2063 OperationIdNounConflictingModelNames
13101267
**Output Message**: OperationId has a noun that conflicts with one of the model names in definitions section. The model name will be disambiguated to '{0}Model'. Consider using the plural form of '{1}' to avoid this. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change.
13111268

0 commit comments

Comments
 (0)