Seguir padrões de codificação
Ao criar um conector personalizado, siga estas práticas recomendadas em seu código.
Definição de API
O apiDefinition.swagger.json, também conhecido como swagger, é onde o comportamento do conector é definido.
- Recuo: use guias simples com quatro espaços, e não use guias complexas.
- Remover espaço à direita: o espaço à direita inclui todos os espaços em branco localizados no final de uma linha quando não há outro caractere em seguida. As tabs complexas contam como um espaço à direita se não houver caracteres em seguida.
Estrutura do arquivo
Para ter uma definição de swagger legível, crie uma definição de API com a seguinte estrutura:
- Versão SwaggerOpenAPI (no momento, apenas a versão 2.0 está disponível)
- Informações sobre o conector (título, descrição, status, contatos)
- Hosts e esquemas disponíveis
- Seção Consome/produz
- Caminhos (definições de ações e gatilhos)
- Definições (tipos de dados usados em ações e gatilhos)
- Parâmetros (parâmetros que podem ser usados nas operações)
Ações e gatilhos
Use o uso de maiúsculas e minúsculas de Pascal no operationId: coloque todas as palavras em maiúsculo (incluindo a primeira). Não adicione hífens (-) ou sublinhados (_) para separar palavras.
Boa
"operationId": "GetMessages",Ruim
"operationId": "getMessages", "operationId": "Get-Messages", "operationId": "Get_Messages",
Resumo e descrição
As operações devem sempre ter um resumo e uma descrição. O resumo será o nome da operação, portanto, mantenha-o curto e preciso, a descrição deve fornecer mais informações e terminar com um ponto (.).
A maioria das descrições são colocadas como dicas nas caixas de parâmetros, certifique-se de fornecer um texto curto e significativo. Descrições e resumos não devem ter o mesmo conteúdo.
Boa
"summary": "List Name", "description": "The list to check for messages.",Ruim
"summary": "List", "description": "List.",
RESPOSTAS
Defina o seu código de sucesso usando um HTTP com tipo de resposta 2xx. Não use default como sua única resposta definida Em vez disso, combine-a com uma definição de sucesso. Se possível, indique também os as respostas 4xx/5xx conhecidas.
Use tipos de erro
4xxquando o problema for causado pelo cliente. Veja alguns exemplos:401 - The username is invalid (it can only contain lowercase letters and numbers)
Use tipos de erro
5xxquando o problema for causado pelo 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." } } }Ruim
{ "responses": { "default": { "description": "OK", "schema": { "type": "string" } } } }
Definições e parâmetros
No caso de parâmetros que aparecem em mais de uma operação, crie um parâmetro de nome na seção parameters em vez de definir este parâmetro em cada operação que o utiliza.
Boa
Neste exemplo, o parâmetro
idé definido emIdInPathe usado nas 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" }, } }O uso de referências em parâmetros e definições tornará o ApiDefinition mais fácil de manter. Por exemplo, se a descrição precisar de uma atualização, isso será feito em apenas um lugar, em vez de todas as operações que a utilizam.
Ruim
{ "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 nas definições e use essa referência nas operações que têm a mesma resposta do objeto.
Boa
Neste exemplo, além de usar um parâmetro referenciado, as operações
GetUsereUpdateUserse referem à mesma resposta do objetoUserResponse, definido uma vez na seçã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 } } } }Ruim
{ "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
Agradecemos muito os comentários sobre problemas com nossa plataforma de conectores ou novas ideias de recursos. Para fornecer comentários, acesseEnviar problemas ou obter ajuda com conectores e selecione o tipo de comentário.