Skip to content
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

Update openapi-authoring-automated-guidelines.md to avoid comfusing #11208

Merged
merged 3 commits into from
Nov 19, 2020
Merged

Update openapi-authoring-automated-guidelines.md to avoid comfusing #11208

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6ecc193
Update openapi-authoring-automated-guidelines.md
jianyexi Oct 15, 2020
8a88006
Update openapi-authoring-automated-guidelines.md
jianyexi Nov 13, 2020
77c7b98
change url of suppressing process
jianyexi Nov 13, 2020
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
56 changes: 38 additions & 18 deletions documentation/openapi-authoring-automated-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
* [Rule Descriptions](#rule-descriptions)

## Error vs Warning
- Rules with severity "Error" have to be addressed for the OpenAPI(swagger) spec to be approved by the reviewers. If there is a strong reason for why the rule cannot be addressed in an OpenAPI(swagger) spec it will be a permanent exception, then [suppression process](https://github.com/Azure/adx-documentation-pr/wiki/Swagger-Validation-Errors-Suppression) must be followed.
- Rules with severity "Error" have to be addressed for the OpenAPI(swagger) spec to be approved by the reviewers. If there is a strong reason for why the rule cannot be addressed in an OpenAPI(swagger) spec it will be a permanent exception, then [suppression process](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/85/Swagger-Suppression-Process) must be followed.

- Rules with severity "Warning" are either strong recommendations made by Azure developer experience team for better SDK/Documentation experience or they point out something to evaluate, for example, the warning for booleans asks the user to evaluate whether the property should be a boolean or not.

Expand Down Expand Up @@ -2349,35 +2349,55 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul
**LastModifiedAt**: April 2, 2020

**How to fix the violation**: Following the ARM specification to modify the schema in the swagger file.
It's recommended to refer to the 'ErrorResponse' in [v2/types.json](https://github.com/Azure/azure-rest-api-specs/blob/master/specification/common-types/resource-management/v2/types.json#L273) which is provided for fixing the error.

The following would be invalid:

```json
"response":{
"default": {
"schema":{
"error":"error msg",
"code": 404,
"message":"some details"
"definitions": {
"ErrorResponse": {
"properties": {
"code": {
"readOnly": true,
"type": "string",
"description": "The error code."
},
"message": {
"readOnly": true,
"type": "string",
"description": "The error message."
}
...
}
}
}

}
```

the correct schema:

```json
"response":{
"default": {
"error":
{
"code": 404,
"message":"some details"
...
"definitions": {
"ErrorResponse": {
"properties": {
"error": {
"type": "object",
"description": "The error object.",
"properties": {
"code": {
"readOnly": true,
"type": "string",
"description": "The error code."
},
"message": {
"readOnly": true,
"type": "string",
"description": "The error message."
}
...
}
}
}
}
}

```

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

**Output Message** : The response schema of operations API "{0}" does not match the ARM specification. Please standardize the schema.

**Description** : The operations API should have a response body schema consistent with the [contract spec](https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/proxy-api-reference.md#exposing-available-operations). The required properties such as `isDataAction`,`display.description` or `display.resource`,must be included.
**Description** : The operations API should have a response body schema consistent with the [contract spec](https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/proxy-api-reference.md#exposing-available-operations). The required properties such as `isDataAction`,`display.description` and `display.resource`,must be included.

**CreatedAt**: July 13, 2020

Expand Down