Seguir os padrões de codificação
Ao criar um conector personalizado, siga estas boas práticas no seu código.
Definição de API
O apiDefinition.swagger.json, também conhecido como Swagger é onde o comportamento do conector é definido.
- Avanço: utilize separadores macios com quatro espaços, não utilize separadores rígidos.
- Remover espaço à direita: o espaço à direita inclui todo o espaço em branco localizado no final de uma linha quando não há outro caráter a seguir. Os separadores rígidos contam como um espaço à direita se não houver nada a seguir.
Estrutura do ficheiro
Para ter uma definição de Swagger legível, crie uma definição de API com a seguinte estrutura:
- Versão SwaggerOpenAPI (atualmente, apenas 2.0 é suportada)
- Informações sobre o conector (título, descrição, estado, contactos)
- Esquemas alojados e suportados
- Secção consome/produz
- Caminhos (definições de ações e acionadores)
- Definições (Tipos de dados utilizados em ações e acionadores)
- Parâmetros (Parâmetros que podem ser utilizados em todas as operações)
Ações e acionadores
Utilize maiúsculas/minúsculas pascal para operationId: capitalize cada palavra (incluindo a primeira). Não adicione hífens (-) ou sublinhados (_) para separar palavras.
Boa
"operationId": "GetMessages",Mau
"operationId": "getMessages", "operationId": "Get-Messages", "operationId": "Get_Messages",
Resumo e descrição
As operações devem ter sempre um resumo e uma descrição. O resumo será o nome da operação, por isso mantenha-a curta e precisa, a descrição deve dar mais informações e terminar com um ponto (.).
A maioria das descrições são colocadas como sugestões nas caixas de parâmetros, certifique-se de que fornece um texto curto e significativo. As descrições e resumos não devem ter o mesmo conteúdo.
Boa
"summary": "List Name", "description": "The list to check for messages.",Mau
"summary": "List", "description": "List.",
RESPOSTAS
Defina o seu código de sucesso utilizando um tipo de resposta 2xx HTTP. Não use default como a sua única resposta definida, emparelhe-a com uma definição de sucesso. Se possível, também enumere as respostas 4xx/5xx conhecidas.
Use erros de tipo
4xxquando o problema originou do lado do cliente, eis alguns exemplos:401 - The username is invalid (it can only contain lowercase letters and numbers)
Use erros de tipo
5xxquando o problema originou no lado do servidor504 - The request timed-out
Boa
{ "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." } } }Mau
{ "responses": { "default": { "description": "OK", "schema": { "type": "string" } } } }
Definições e parâmetros
Para parâmetros que apareçam em mais de uma operação, crie um parâmetro de nome na secção parameters em vez de definir este parâmetro em cada operação que o utilize.
Boa
Neste exemplo, o parâmetro
idé definido emIdInPathe usado em operaçõesGetMemberGroupseRemoveMemberFromGroup.{ "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" }, } }A utilização de referências em parâmetros e definições tornará a ApiDefinition mais sustentável. Por exemplo, se a descrição precisar de uma atualização, será feita em apenas um lugar, em vez de todas as operações que a utilizam.
Mau
{ "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 } } } } }
Crie uma entrada em definições e use essa referência através de operações que tenham a mesma resposta de objeto.
Boa
Neste exemplo, para além da utilização de um parâmetro referenciado, as operações
GetUsereUpdateUserreferenciam o mesmoUserResponsede resposta de objeto, definidas uma vez na secçãodefinitions.{ "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 } } } }Mau
{ "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 } } } }
Informações relacionadas
Enviar comentários
Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.