Skip to content

Commit

Permalink
Update openapi-authoring-automated-guidelines.md (Azure#13859)
Browse files Browse the repository at this point in the history 
* add rule

Co-authored-by: jianye xi <[email protected]>
  • Loading branch information
@jianyexi @mkarmark
2 people authored and mkarmark committed Jul 20, 2021
1 parent a77ab69 commit 170b35e
Showing 1 changed file with 56 additions and 8 deletions.
64 changes: 56 additions & 8 deletions documentation/openapi-authoring-automated-guidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,6 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| [R3030](#R3030) | [PathResourceProviderMatchNamespace](#R3030) | 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 |
| [R3020](#r3020) | [PathResourceProviderNamePascalCase](#r3020) | ARM OpenAPI(swagger) specs |
Expand All @@ -71,6 +69,8 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| [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 |
| [R3027](#r3027) | [TrackedResourceListByResourceGroup](#r3027) | ARM OpenAPI(swagger) specs |
| [R3028](#r3028) | [TrackedResourceListBySubscription](#r3028) | ARM OpenAPI(swagger) specs |
| [R2004](#r2004) | [NonApplicationJsonType](#r2004) | ARM OpenAPI(swagger) specs |
| [R4014](#r4014) | [AllResourcesMustHaveGetOperation](#r4014) | ARM OpenAPI(swagger) specs |
### SDK Violations
Expand Down Expand Up @@ -116,7 +116,7 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
| [R4034](#r4034) | [AzureResourceTagsSchemaValidation](#r4034) | ARM OpenAPI(swagger) specs |
| [R4035](#r4035) | [PrivateEndpointResourceSchemaValidation](#r4035) | ARM OpenAPI(swagger) specs |
| [R4036](#r4036) | [ImplementPrivateEndpointAPIs](#r4036) | ARM OpenAPI(swagger) specs |

| [R4037](#r4037) | [MissingTypeObject](#r4037) | ARM and Data plan OpenAPI(swagger) specs |
#### SDK Warnings

| Id | Rule Name | Applies to |
Expand Down Expand Up @@ -292,7 +292,7 @@ If the resource pointed by the rule is not a tracked resource, this warning may
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="r3027" />R3027 TrackedResourceListByResourceGroup
**Category** : ARM Error
**Category** : ARM Warning

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

Expand All @@ -313,7 +313,7 @@ If the resource pointed by the rule is not a tracked resource or the operation t
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="r3028" />R3028 TrackedResourceListBySubscription
**Category** : ARM Error
**Category** : ARM Warning

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

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

**Output Message**: A '{0}' operation '{1}' with x-ms-long-running-operation extension must have a valid terminal success status code {2}.

**Description**: The allowed response status codes for a long DELETE operation are "200", "204". The allowed response status codes for a POST operation are "200", "201" ,"202", & "204". The allowed response status codes for a PUT operation are "200" & "201".
**Description**: For ARM spec, the allowed response status codes for a long DELETE operation are "200" & "204"; the allowed response status codes for a POST operation are "200", "201" ,"202", & "204"; the allowed response status codes for a PUT/PATCH operation are "200" & "201".
For Data plane spec, the allowed response status codes for a long DELETE operation are "200","202", & "204"; the allowed response status codes for a POST operation are "200", "201" ,"202", & "204"; the allowed response status codes for a PUT/PATCH operation are "200","201", & "202".

**Why the rule is important**: This will ensure that the DELETE/POST/PUT operations are designed correctly.Please refer [here](./swagger-extensions.md#x-ms-long-running-operation) for further details.

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

In case of LRO Post operation with return schema, it MAY be ambiguous for the SDK to understand automatically what the return schema is modeling. To avoid any confusion that would lead SDK to incorrectly instantiate the return type, service team needs to explain if the return schema is modeling a result from a "Location" header, or from an "Azure-AsyncOperation" header.

More details on LRO operation could be found [here](https://github.com/Azure/adx-documentation-pr/blob/master/sdks/LRO/LRO_AzureSDK.md)
More details on LRO operation could be found [here](https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-long-running-operation)

**How to fix the violation**: For a Post LRO operation, add "x-ms-long-running-operation-options" extension with "final-state-via" property.
``` json
Expand Down Expand Up @@ -3459,4 +3460,51 @@ GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{

**How to fix the violation**: Please add the missing private endpoint API path and operation to the swagger.

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)
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="r4037"></a>R4037 MissingTypeObject

**Category** : SDK Error

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

**Output Message** : The schema '{json path}' is considered an object but without a 'type:object', please add the missing 'type:object'.

**Description**: The rule should apply to any schema with "properties" or "additionalProperties". It is to ensure a schema with "properties" or "additionalProperties" must have explicit "type:object" statement, which means a schema is an object.

**CreatedAt**: May 24, 2021

**LastModifiedAt**: May 24, 2021

**Why this rule is important**: The semantics of with and without "type:object" are different. With “type:object” means “it has to be an object”. Without “type: object” means “it could be any type”. Azure SDK Track 2 generator will honor the difference, and generate different SDK codes.
A free-form object would like:

**How to fix the violation**:
Just add the missing 'type:object'.

The following would be valid:

```json
"foo": {
"type":"object",
"properties": {
"a" : {
"type":"string"
}
...
}
}
```
The following would be invalid by default (unless you do it on purpose , then a suppression is required):

```json
"foo": {
"properties": {
"a" : {
"type":"string"
}
...
}
```
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 170b35e

Please sign in to comment.