코딩 표준 따르기
사용자 지정 커넥터를 만들 때 코드에서 다음 모범 사례를 따르십시오.
API 정의
swagger라고도 하는 apiDefinition.swagger.json은 커넥터의 동작이 정의되는 곳입니다.
- 들여쓰기: 네 개의 공백이 있는 부드러운 탭을 사용하고 딱딱한 탭은 사용하지 마십시오.
- 후행 공백 제거: 후행 공백은 뒤에 다른 문자가 없을 때 줄 끝에 있는 모든 공백을 포함합니다. 하드 탭은 뒤에 오는 것이 없으면 후행 공백으로 간주됩니다.
파일의 구조
읽을 수 있는 Swagger 정의를 사용하려면 다음 구조로 API 정의를 만드십시오.
- SwaggerOpenAPI 버전(현재 2.0만 지원)
- 커넥터에 대한 정보(제목, 설명, 상태, 연락처)
- 호스트 및 지원되는 체계
- 소비/생산 섹션
- 경로(작업 및 트리거의 정의)
- 정의(작업 및 트리거에 사용되는 데이터 유형)
- 매개 변수(작업 전반에 걸쳐 사용할 수 있는 매개 변수)
작업 및 트리거
operationId에 파스칼 케이싱 사용: 모든 단어(첫 단어 포함)를 대문자로 표시합니다. 하이픈(-) 또는 밑줄(_)을 추가하여 단어를 구분하지 마세요.
적절
"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 } } } }
관련 정보
피드백 제공
커넥터 플랫폼 관련 문제 또는 새로운 기능 아이디어에 대한 피드백을 주셔서 정말 감사합니다. 피드백을 제공하려면 문제 제출 또는 커넥터 관련 도움말 보기로 이동하여 피드백 유형을 선택하십시오.