From d0cf020a892e9e72b93aa1e41e22d9e0ea58e149 Mon Sep 17 00:00:00 2001 From: jianye xi Date: Tue, 24 Nov 2020 17:09:49 +0800 Subject: [PATCH 1/3] add R4028 --- .../openapi-authoring-automated-guidelines.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/documentation/openapi-authoring-automated-guidelines.md b/documentation/openapi-authoring-automated-guidelines.md index d05cf148963f..e59061b2edd1 100644 --- a/documentation/openapi-authoring-automated-guidelines.md +++ b/documentation/openapi-authoring-automated-guidelines.md @@ -109,6 +109,7 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an | [R4008](#r4008) | [AvoidEmptyResponseSchema](#r4008) | ARM OpenAPI(swagger) specs | | [R4012](#r4012) | [XmsPageableMustHaveCorrespondingResponse](#r4012) | ARM OpenAPI(swagger) specs | | [R4013](#r4013) | [IntegerTypeMustHaveFormat](#r4013) | ARM OpenAPI(swagger) specs | +| [R4028](#r4028) | [ValidResponseCodeRequired](#r4028) | ARM OpenAPI(swagger) specs | #### SDK Warnings @@ -2990,3 +2991,43 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul 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) + +### R4028 ValidResponseCodeRequired + +**Category** : SDK Error + +**Applies to** : ARM OpenAPI(swagger) specs + +**Output Message** : There is no declared valid status code. + +**Description** : Every operation response must contain a valid code like "200","201","202" or "204" which indicates the operation is succeed and it's not allowed that a response schema just contains a "default" code. + +**Why this rule is important**: If a Swagger just contains "default" status code, this actually means "everything is an error". All track2 SDK will systematically raise an exception at runtime, if there is no declared valid status code. + +**CreatedAt**: November 23, 2020 + +**LastModifiedAt**: November 23, 2020 + +**How to fix the violation**: Add a valid response code . +The following would be valid: + +```json +... + "responses": { + "200": { + "description": "Succeeded", + "schema": { + "$ref": "#/definitions/MySimpleResource" + } + }, + "default": { + "description": "Error response describing why the operation failed.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } +... +``` +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) \ No newline at end of file From 9e429d5607c2ebdea9c8cc67744cd10de2bfad4c Mon Sep 17 00:00:00 2001 From: Ruoxuan Wang <52271048+ruowan@users.noreply.github.com> Date: Mon, 30 Nov 2020 13:14:32 +0800 Subject: [PATCH 2/3] update doc (#11843) * update doc * update description * format --- .../openapi-authoring-automated-guidelines.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/documentation/openapi-authoring-automated-guidelines.md b/documentation/openapi-authoring-automated-guidelines.md index e59061b2edd1..48614a04ea9c 100644 --- a/documentation/openapi-authoring-automated-guidelines.md +++ b/documentation/openapi-authoring-automated-guidelines.md @@ -110,6 +110,7 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an | [R4012](#r4012) | [XmsPageableMustHaveCorrespondingResponse](#r4012) | ARM OpenAPI(swagger) specs | | [R4013](#r4013) | [IntegerTypeMustHaveFormat](#r4013) | ARM OpenAPI(swagger) specs | | [R4028](#r4028) | [ValidResponseCodeRequired](#r4028) | ARM OpenAPI(swagger) specs | +| [R4029](#r4029) | [UniqueClientParameterName](#r4029) | ARM OpenAPI(swagger) specs | #### SDK Warnings @@ -142,6 +143,7 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an | [R2029](#r2029) | [PageableOperation](#r2029) | ARM and Data plane OpenAPI(swagger) specs | | [R4006](#r4006) | [DeprecatedXmsCodeGenerationSetting](#r4006) | ARM and Data plane OpenAPI(swagger) specs | | [R4024](#r4024) | [PreviewVersionOverOneYear](#r4024) | ARM OpenAPI(swagger) specs | +| [R4030](#r4030) | [UniqueXmsExample](#r4030) | ARM OpenAPI(swagger) specs | ### RPaaS Violations @@ -3030,4 +3032,86 @@ The following would be valid: } ... ``` +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) + + +### R4029 UniqueClientParameterName + +**Category** : SDK Error + +**Applies to** : ARM OpenAPI(swagger) specs + +**Output Message** : Do not have duplicate name of client parameter name, make sure every client parameter name unique. + +**Description** : This may cause a problem when different swagger files come together. If two APIs with different client name have the same client parameter subscriptionId, but with different reference name in swaggers, the generated model will also have two clients with two client parameters subscriptionId and subscriptionId1 (the latter one has been renamed to avoid collision). We should ensure that the client parameters are all unique. + +**Why this rule is important**: Make sure no conflict in SDK generation. + +**CreatedAt**: November 30, 2020 + +**LastModifiedAt**: November 30, 2020 + +**How to fix the violation**: Remove duplicate client parameter, ref to the same one. +The following would be valid: + +```json +... + "/api": { + "get": { + "parameters": [ + { + "$ref": "#/parameters/ApiVersionParameter" + }, + { + // ref to the same subcriptionId + "$ref": "#/parameters/subscriptionIdParameter" + }, + ], + }, + "patch": [ + { + "$ref": "#/parameters/ApiVersionParameter" + }, + { + "$ref": "#/parameters/subscriptionIdParameter" + }, + ] + } +... +``` +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) + + +### R4030 UniqueXmsExample + +**Category** : SDK Warning + +**Applies to** : ARM OpenAPI(swagger) specs + +**Output Message** : Do not have duplicate name of x-ms-example, make sure every x-ms-example name unique. Duplicate x-ms-example: {ExampleName} + +**Description** : x-ms-example name should be unique. + +**Why this rule is important**: Duplicate example name will bring trouble for test codegen. For example: hard to config used example. + +**CreatedAt**: November 30, 2020 + +**LastModifiedAt**: November 30, 2020 + +**How to fix the violation**: Rename duplicate x-ms-example name +The following would be valid: + +```json +... +"x-ms-examples": { + "Create resource": { + "$ref": "./examples/createResource" + }, + "Update resource":{ + "$ref": "./examples/updateResource" + } + + } +... +``` 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) \ No newline at end of file From 33a8d6ba37ccf4d2e4e17f7e9cad8cc94cb5089f Mon Sep 17 00:00:00 2001 From: jianye xi Date: Mon, 30 Nov 2020 13:41:05 +0800 Subject: [PATCH 3/3] add scope --- documentation/openapi-authoring-automated-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/openapi-authoring-automated-guidelines.md b/documentation/openapi-authoring-automated-guidelines.md index 48614a04ea9c..696357898084 100644 --- a/documentation/openapi-authoring-automated-guidelines.md +++ b/documentation/openapi-authoring-automated-guidelines.md @@ -3043,7 +3043,7 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul **Output Message** : Do not have duplicate name of client parameter name, make sure every client parameter name unique. -**Description** : This may cause a problem when different swagger files come together. If two APIs with different client name have the same client parameter subscriptionId, but with different reference name in swaggers, the generated model will also have two clients with two client parameters subscriptionId and subscriptionId1 (the latter one has been renamed to avoid collision). We should ensure that the client parameters are all unique. +**Description** : This may cause a problem when different swagger files come together. If two APIs with different client name have the same client parameter subscriptionId, but with different reference name in swaggers, the generated model will also have two clients with two client parameters subscriptionId and subscriptionId1 (the latter one has been renamed to avoid collision). We should ensure that the client parameters are all unique in the same API version. **Why this rule is important**: Make sure no conflict in SDK generation. @@ -3090,7 +3090,7 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul **Output Message** : Do not have duplicate name of x-ms-example, make sure every x-ms-example name unique. Duplicate x-ms-example: {ExampleName} -**Description** : x-ms-example name should be unique. +**Description** : x-ms-example name should be unique in the same API version. **Why this rule is important**: Duplicate example name will bring trouble for test codegen. For example: hard to config used example.