遵从编码标准

项目
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 还引用在 definitions 部分中定义过一次的相同对象响应 UserResponse。

{
  "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 定义

文件的结构

操作和触发器

摘要和说明

响应

定义和参数

相关信息

提供反馈

其他资源