遵循編碼標準

發行項
06/27/2024

建立自訂連接器時，請在程式碼中遵循以下良好的做法。

API 定義

apiDefinition.swagger.json (也稱為 Swagger) 用於定義連接器行為。

縮排：使用有四個空格的軟定位點，不要使用硬定位點。
移除後置空格：當行尾後沒有其他字元時，句尾空格包括位於行尾的所有空格。如果後面沒有任何內容，硬製索引標籤會算作句尾空格。

檔案的結構

若要使用可讀取的 Swagger 定義，請建立具有以下結構的 API 定義：

SwaggerOpenAPI 版本 (目前只支援 2.0)
連接器的資訊 (標題、描述、狀態、連絡人)
主機和支援的配置
使用/產生區段
路徑 (動作和觸發程序的定義)
定義 (動作和觸發程序中使用的資料類型)
參數 (可跨作業使用的參數)

動作和觸發程序

operationId 使用 pascal 大小寫：每個單字 (包括第一個單字) 大寫。不要新增連字號 (-) 或底線 (_) 來分隔單字。

很好
```
"operationId": "GetMessages",
```

不良

"operationId": "getMessages",
"operationId": "Get-Messages",
"operationId": "Get_Messages",

摘要和描述

作業應一律擁有摘要和描述。摘要將是作業的名稱，因此請保持簡短精確，描述應提供更多資訊，並以句點 (.) 結尾。

大部分描述都會做為 [提示] 放置在參數方塊中，請務必提供簡短且有意義的文字。描述和摘要不應為相同的內容。

很好

"summary": "List Name",
"description": "The list to check for messages.",

不良

"summary": "List",
"description": "List.",

回覆

使用 HTTP 2xx 回覆類型定義您的成功程式碼。請勿使用 default 做為唯一定義的回覆，而是將其與成功的定義配對。如果可能，也請列出已知的 4xx/5xx 回覆。

當問題源自於用戶端時，請使用 4xx 類型錯誤，以下是一些範例：
- 401 - The username is invalid (it can only contain lowercase letters and numbers)
當問題源自伺服器端時，請使用 5xx 類型錯誤
- 504 - The request timed-out

很好

{
  "responses": {
    "200": {
      "description": "OK",
      "schema": {
        "$ref": "#/definitions/Message"
      }
    },
    "400": {
      "description": "Bad Request"
    },
    "404": {
      "description": "Not Found"
    },
    "401": {
      "description": "Unauthorized"
    },
    "403": {
      "description": "Forbidden"
    },
    "500": {
      "description": "Internal Server Error. Unknown error occurred"
    },
    "default": {
      "description": "Operation Failed."
    }
  }
}

不良

{
  "responses": {
    "default": {
      "description": "OK",
      "schema": {
        "type": "string"
      }
    }
  }
}

定義和參數

對於出現在多個作業中的參數，請在 parameters 區段建立名稱參數，而不是在使用它的每個作業中定義此參數。

很好

在此範例中，參數 id 定義在 IdInPath 中，並用於作業 GetMemberGroups 和 RemoveMemberFromGroup。

{
  "paths": {
    "/groups/{id}/getMemberGroups": {
      "post": {
        "summary": "Get groups of a user",
        "description": "Get the groups a user is a member of.",
        "operationId": "GetMemberGroups",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          // response definitions
        }
      }
    },
    "/groups/{id}/members/{memberId}/delete": {
      "delete": {
        "summary": "Remove member",
        "description": "Delete a member from a group.",
        "operationId": "RemoveMemberFromGroup",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          },
          {
            "name": "memberId",
            "in": "path",
            "required": true,
            "description": "The Id of the member to be deleted.",
            "x-ms-summary": "Member Id",
            "type": "string"
          }
        ],
        "responses": {
          // response definitions
        }
      }
    }
  },
  // definitions
  "parameters":{
    "IdInPath": {
      "name": "id",
      "in": "path",
      "description": "Unique identifer of a group (Ex. 'id_group1').",
      "required": true,
      "x-ms-summary": "Group Id",
      "type": "string"
    },
  }
}

在參數和定義上使用參考，可讓 ApiDefinition 更易於維護。例如，如果描述需要更新，這只會在一個地方完成，而不是所有使用該描述的作業。

不良

{
  "paths": {
    "/groups/{id}/getMemberGroups": {
      "post": {
        "summary": "Get groups of a user",
        "description": "Get the groups a user is a member of.",
        "operationId": "GetMemberGroups",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Unique identifer of a group (Ex. 'id_group1').",
            "required": true,
            "x-ms-summary": "Group Id",
            "type": "string"
          }
        ],
        "responses": {
          // response definitions
        }
      }
    },
    "/groups/{id}/members/{memberId}/delete": {
      "delete": {
        "summary": "Remove member",
        "description": "Delete a member from a group.",
        "operationId": "RemoveMemberFromGroup",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Unique identifer of a group (Ex. 'id_group1').",
            "required": true,
            "x-ms-summary": "Group Id",
            "type": "string"
          },
          {
            "name": "memberId",
            "in": "path",
            "required": true,
            "description": "The Id of the member to be deleted.",
            "x-ms-summary": "Member Id",
            "type": "string"
          }
        ],
        "responses": {
          // response definitions
        }
      }
    }
  }
}

在定義上建立的項目，並在具有相同物件回覆的各項作業中使用該參考。

很好

在此範例中，除了使用參考的參數之外，作業 GetUser 和 UpdateUser 參考相同的物件回覆 UserResponse，其在 definitions 區段中定義過一次。

{
  "paths": {
    "/v1.0/users/{id}": {
      "get": {
        "summary": "Get user",
        "description": "Get details for a user.",
        "operationId": "GetUser",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "$ref": "#/definitions/UserResponse"
            }
          }
        }
      },
      "patch": {
        "summary": "Update user",
        "description": "Update the info for a user.",
        "operationId": "UpdateUser",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          "201": {
            "description": "Accepted",
            "schema": {
              "$ref": "#/definitions/UserResponse"
            }
          }
        },
        "deprecated": false,
        "x-ms-no-generic-test": true
      }
    },
  },
  // definitions
  "definitions":{
   "UserResponse": {
      "type": "object",
      "properties": {
        "id": {
          "description": "The unique identifier for the user.",
          "type": "string",
          "x-ms-summary": "Id"
        },
        "email": {
          "description": "The email associated to the user.",
          "type": "string",
          "x-ms-summary": "Email"
        },
        // more fields here
      }
    }
  }
}

不良

{
  "paths": {
    "/v1.0/users/{id}": {
      "get": {
        "summary": "Get user",
        "description": "Get details for a user.",
        "operationId": "GetUser",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "$ref": "#/definitions/UserResponse"
            }
          }
        }
      },
      "patch": {
        "summary": "Update user",
        "description": "Update the info for a user.",
        "operationId": "UpdateUser",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          "201": {
            "description": "Accepted",
            "schema": {
              "$ref": "#/definitions/UserResponse"
            }
          }
        },
        "deprecated": false,
        "x-ms-no-generic-test": true
      }
    },
  },
  // definitions
  "definitions":{
   "UserResponse": {
      "type": "object",
      "properties": {
        "id": {
          "description": "The unique identifier for the user.",
          "type": "string",
          "x-ms-summary": "Id"
        },
        "email": {
          "description": "The email associated to the user.",
          "type": "string",
          "x-ms-summary": "Email"
        },
        // more fields here
      }
    }
  }
}

提供意見反應

非常感謝您提供有關連接器平台問題，或新功能構想的意見反應。若要提供意見反應，請移至提交問題或取得連接器說明，然後選取您的意見反應類型。

共用方式為

遵循編碼標準

API 定義

檔案的結構

動作和觸發程序

摘要和描述

回覆

定義和參數

提供意見反應

其他資源

共用方式為

遵循編碼標準

API 定義

檔案的結構

動作和觸發程序

摘要和描述

回覆

定義和參數

相關資訊

提供意見反應

其他資源