Skip to content

Update openapi-authoring-automated-guidelines.md #13859

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jianye Xi (jianyexi) merged 8 commits into from
Jun 1, 2021
Merged

Update openapi-authoring-automated-guidelines.md #13859

Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5bf7cf1
Update openapi-authoring-automated-guidelines.md
jianyexi Apr 9, 2021
d9b9938
add rule
May 24, 2021
ceb1e61
up
May 24, 2021
a29b8a1
up
May 24, 2021
4610892
up
May 25, 2021
0094986
up
May 25, 2021
911861f
up
May 25, 2021
14152b5
up
May 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 65 additions & 8 deletions documentation/openapi-authoring-automated-guidelines.md
View file
Open in desktop
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](#r4032) | [MissingTypeObject](#r4037) | ARM 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,7 @@ 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**: 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 +1907,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)
Comment thread
jianyexi marked this conversation as resolved.

**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 +3459,61 @@ 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**: This rule ensure that any schema whose type is 'object' must defines its type explicity, as a schema without type indicates a free-form schema which means it can be any type. For this rule, a schema with keyword 'properties' or 'additionalProperties' is considered an object schema.
Comment thread
jianyexi marked this conversation as resolved.
Outdated

**CreatedAt**: May 24, 2021

**LastModifiedAt**: May 24, 2021

**Why this rule is important**: It's used to differentiate free-form object and any type , as the SDK track1 doesn’t make a difference between the two syntax.
Comment thread
jianyexi marked this conversation as resolved.
Outdated
A free-form object would like:
```json
"foo": {
"type":"object"
}
```
A any type schema would like:
```json
"foo": {
}
```

**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:

```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)