From 6ecc193882df58854928bb6f900f0b3c2a687d71 Mon Sep 17 00:00:00 2001 From: JianyeXi <59603451+jianyexi@users.noreply.github.com> Date: Thu, 15 Oct 2020 12:59:28 +0800 Subject: [PATCH 1/3] Update openapi-authoring-automated-guidelines.md --- .../openapi-authoring-automated-guidelines.md | 52 +++++++++++++------ 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/documentation/openapi-authoring-automated-guidelines.md b/documentation/openapi-authoring-automated-guidelines.md index 32866c30d025..740a238f4d76 100644 --- a/documentation/openapi-authoring-automated-guidelines.md +++ b/documentation/openapi-authoring-automated-guidelines.md @@ -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." + } + ... + } } } - } +} ``` From 8a880066556513ec8d9cb40e4d758a84fb275a42 Mon Sep 17 00:00:00 2001 From: JianyeXi <59603451+jianyexi@users.noreply.github.com> Date: Fri, 13 Nov 2020 10:11:38 +0800 Subject: [PATCH 2/3] Update openapi-authoring-automated-guidelines.md --- documentation/openapi-authoring-automated-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/openapi-authoring-automated-guidelines.md b/documentation/openapi-authoring-automated-guidelines.md index 740a238f4d76..21c2224c9549 100644 --- a/documentation/openapi-authoring-automated-guidelines.md +++ b/documentation/openapi-authoring-automated-guidelines.md @@ -2778,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 From 77c7b98153e555917583b82303f06f2c78f6f2ca Mon Sep 17 00:00:00 2001 From: JianyeXi <59603451+jianyexi@users.noreply.github.com> Date: Fri, 13 Nov 2020 10:36:51 +0800 Subject: [PATCH 3/3] change url of suppressing process --- documentation/openapi-authoring-automated-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/openapi-authoring-automated-guidelines.md b/documentation/openapi-authoring-automated-guidelines.md index 21c2224c9549..d05cf148963f 100644 --- a/documentation/openapi-authoring-automated-guidelines.md +++ b/documentation/openapi-authoring-automated-guidelines.md @@ -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.