Skip to content

Commit

Permalink
add lint rule R4005,R4006 to guidelines doc (Azure#8770)
Browse files Browse the repository at this point in the history 
* add lint rule R4005,R4006  to doc

* update doc

* update doc

* update some rules description and security level

* update

* update
  • Loading branch information
@jianyexi @00Kai0
jianyexi authored and 00Kai0 committed Oct 12, 2020
1 parent 858c2ca commit 3330236
Showing 1 changed file with 102 additions and 20 deletions.
122 changes: 102 additions & 20 deletions documentation/openapi-authoring-automated-guidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| [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 |
| [R3020](#r3020) | [PathResourceProviderNamePascalCase](#r3020) | ARM OpenAPI(swagger) specs |
| [R3021](#r3021) | [PathResouceTypeNameCamelCase](#r3021) | ARM OpenAPI(swagger) specs |
| [R4004](#r4004) | [OperationIdRequired](#r4004) | ARM OpenAPI(swagger) specs |

#### ARM Warnings

Expand All @@ -60,12 +63,6 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| [R2057](#r2057) | [InvalidSkuModel](#r2057) | ARM OpenAPI(swagger) specs |
| [R3010](#r3010) | [TrackedResourceListByImmediateParent](#r3010) | ARM OpenAPI(swagger) specs |
| [R2004](#r2004) | [NonApplicationJsonType](#r2004) | ARM OpenAPI(swagger) specs |
| [R4004](#r4004) | [OperationIdRequired](#r4004) | ARM OpenAPI(swagger) specs |
| [R3020](#r3020) | [PathResourceProviderNamePascalCase](#r3020) | ARM OpenAPI(swagger) specs |
| [R3021](#r3021) | [PathResourceTypeNameCamelCase](#r3021) | ARM OpenAPI(swagger) specs |
| [R3015](#r3015) | [EnumMustHaveType](#r3015) | ARM OpenAPI(swagger) specs |
| [R3024](#r3024) | [EnumUniqueValue](#r3024) | ARM OpenAPI(swagger) specs |
| [R3029](#r3029) | [EnumMustNotHaveEmptyValue](#r3024) | ARM OpenAPI(swagger) specs |

### SDK Violations

Expand Down Expand Up @@ -96,6 +93,10 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| [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 |
| [R3015](#r3015) | [EnumMustHaveType](#r3015) | ARM and Data plan OpenAPI(swagger) specs |
| [R3024](#r3024) | [EnumUniqueValue](#r3024) | ARM and Data plan OpenAPI(swagger) specs |
| [R3029](#r3029) | [EnumMustNotHaveEmptyValue](#r3024) | ARM and Data plan OpenAPI(swagger) specs |
| [R4005](#r4005) | [UniqueXmsEnumName](#r4005) | ARM and Data plane OpenAPI(swagger) specs |

#### SDK Warnings

Expand Down Expand Up @@ -126,6 +127,7 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| [R2010](#r2010) | [LongRunningOperationsOptionsValidator](#r2010) | ARM and Data plane OpenAPI(swagger) specs |
| [R2007](#r2007) | [LongRunningOperationsWithLongRunningExtension](#r2007) | ARM OpenAPI(swagger) specs |
| [R2029](#r2029) | [PageableOperation](#r2029) | ARM and Data plane OpenAPI(swagger) specs |
| [R4006](#r4006) | [DeprecatedXmsCodeGenerationSetting](#r4006) | ARM and Data plane OpenAPI(swagger) specs |

### Documentation

Expand Down Expand Up @@ -1898,13 +1900,13 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul

### <a name="r4004" ></a>R4004 OperationIdRequired

**Category** : ARM Warning
**Category** : ARM Error

**Applies to** : ARM OpenAPI(swagger) specs

**Output Message** : Missing operationId. path:'${operation path}' operation:'${operation}'.

**Description** : Each operation must has a unique operationId.
**Description** : Each operation must haave a unique operationId.

**CreatedAt** : February 18, 2020

Expand All @@ -1914,6 +1916,8 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul

**How to fix the violation**: Add the right operationId for each operation

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="r3020" ></a>R3020 PathResourceProviderNamePascalCase

**Category** : ARM Warning
Expand Down Expand Up @@ -1978,9 +1982,7 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul

**Output Message** : Resource type naming SHOULD follow camel case. Path: {your path}

**Description** :

Resource type or other identifiers (include: namespace, entityTypes) SHOULD follow camel case. (e.g. Microsoft.Insights/components/proactiveDetectionConfigs, not ProactiveDetectionConfig)
**Description** : Resource type or other identifiers (include: namespace, entityTypes) SHOULD follow camel case. (e.g. Microsoft.Insights/components/proactiveDetectionConfigs, not ProactiveDetectionConfig)

For more detail, pls refer to https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#172-casing

Expand Down Expand Up @@ -2028,13 +2030,13 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul

### <a name="r3024" ></a>R3024 EnumUniqueValue

**Category** : ARM Warning
**Category** : SDK Error

**Applies to** : ARM and Data Plane OpenAPI(swagger) specs

**Output Message** : Enum must not contain case-insensitive duplicated value and make sure every value in enum unique.
**Output Message** : Enum must not contain duplicated value (case insentive).

**Description** : Case-insensitive value in enum mean the same value.
**Description** : Enum must not contain duplicated value (case insentive).

**CreatedAt**: February 18, 2020

Expand Down Expand Up @@ -2071,13 +2073,13 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul

### <a name="r3015" ></a>R3015 EnumMustHaveType

**Category** : ARM Warning
**Category** : SDK Error

**Applies to** : ARM and Data Plane OpenAPI(swagger) specs

**Output Message** : Enum must define its type and "object" type is not allowed due to Autorest refuse to parse it.
**Description** : Enum must define its type "string". If not it will block SDK generation. If define type as "object" , the new Autorest refuse to parse it.
**Output Message** : Enum must define its type. All values in an enum must adhere to the specified type.

**Description** : Enum must define type, and type must not be object. Or it will fail SDK auto-generation.

**CreatedAt**: February 18, 2020

Expand Down Expand Up @@ -2128,13 +2130,13 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul

### <a name="r3029" ></a>R3029 EnumMustNotHaveEmptyValue

**Category** : ARM Warning
**Category** : SDK Error

**Applies to** : ARM and Data Plane OpenAPI(swagger) specs

**Output Message** : Enum value must not contain empty value.

**Description** : Empty value is not allowed in enum value and meanless.
**Description** : Emum must not be empty, or contain special character, like space, tab, etc. It will lead to code generation failure in downstream pipeline.

**CreatedAt**: February 18, 2020

Expand Down Expand Up @@ -2234,3 +2236,83 @@ Eg:
```

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="r4005" ></a>R4005 UniqueXmsEnumName

**Category** : SDK Error

**Applies to** : ARM and Data plane OpenAPI(swagger) specs

**Output Message** : Must not have duplicate name in x-ms-enum extension , make sure every x-ms-enum name unique.

**Description** : Must not have duplicate name in x-ms-enum extension.

**CreatedAt**: March 18, 2020

**LastModifiedAt**: March 18, 2020

**How to fix the violation**: Update the duplicate x-ms-enum name :

The following would be invalid:
```json
"State": {
"description": "The state of the configuration store.",
"enum": [
"Failed",
"Canceled"
],
"type": "string",
"readOnly": true,
"x-ms-enum": {
"name": "DuplicateName",
"modelAsString": true
}
},
"status": {
"description": "The state code.",
"enum": [
"Success",
"FAILED"
],
"readOnly": true,
"type": "string",
"x-ms-enum": {
"name": "DuplicateName",
"modelAsString": true
}
}
}
```

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="r4006" ></a>R4006 DeprecatedXmsCodeGenerationSetting

**Category** : SDK Warning

**Applies to** : ARM and Data plane OpenAPI(swagger) specs

**Output Message** : The x-ms-code-generation-setting extension is being deprecated. Please remove it and move settings to readme file for code generation.

**Description** : The x-ms-code-generation-settings is being deprecated. AutoRest (v3) is using settings in readme file for code generation and will stop supporting it inside the swagger file. Please ensure to remove the parameter from swagger spec and move settings to readme.

**CreatedAt**: March 18, 2020

**LastModifiedAt**: March 18, 2020

**How to fix the violation**: Since the only value of this extension today is to override the client name, which could be done with a 'title' line in the readme file,you could remove the extension from swagger spec and move settings to readme.

The following would be invalid:

```json
"info": {
"version": "2016-05-16",
"x-ms-code-generation-settings": {
"name": "AnalysisServicesManagementClient"
}
}
```

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)


0 comments on commit 3330236

Please sign in to comment.