Соблюдение стандартов кодирования
При создании пользовательского соединителя следуйте этим рекомендациям в своем коде.
Определение API
apiDefinition.swagger.json, также известный как Swagger, определяет поведение соединителя.
- Отступ: используйте мягкие табуляции с четырьмя пробелами, не используйте жесткие табуляции.
- Удалите конечный пробел: конечный пробел включает все пробелы, расположенные в конце строки, когда за ним нет другого символа. Жесткие табуляторы считаются конечным пробелом, если за ними ничего не следует.
Структура файла
Чтобы иметь удобочитаемое определение Swagger, создайте определение API со следующей структурой:
- Версия SwaggerOpenAPI (в настоящее время поддерживается только 2.0)
- Информация о соединителе (название, описание, статус, контакты)
- Узел и поддерживаемые схемы
- Раздел "Потребляет/производит"
- Пути (определения действий и триггеров)
- Определения (типы данных, используемые в действиях и триггерах)
- Параметры (параметры, которые можно использовать в разных операциях)
Действия и триггеры
Используйте оболочку Pascal для 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ссылаются на один и тот же ответ объекта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 } } } }
Дополнительные сведения
Предоставление отзывов
Для нас очень важны отзывы о проблемах с нашей платформой соединителей и новые идеи о функциях. Чтобы оставить отзыв, выберите пункт Сообщить о проблемах или получить помощь с соединителями и выберите тип отзыва.