Partilhar via

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.

  • Recuo: use guias suaves com quatro espaços, não use guias rígidas.
  • 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á nenhum outro caráter seguindo-o. 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:

  1. Versão SwaggerOpenAPI (atualmente, apenas 2.0 é suportada)
  2. Informações sobre o conector (título, descrição, estado, contactos)
  3. Esquemas alojados e suportados
  4. Secção consome/produz
  5. Caminhos (definições de ações e acionadores)
  6. Definições (Tipos de dados utilizados em ações e acionadores)
  7. Parâmetros (Parâmetros que podem ser utilizados em todas as operações)

Ações e acionadores

Use o invólucro pascal para operationId: colocar todas as palavras em maiúsculas (incluindo a primeira). Não adicione hífenes (-) ou sublinhados (_) para separar palavras.

  • Bom

    "operationId": "GetMessages",

  • Ruim

    "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, portanto, mantenha-o curto e preciso, 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 os resumos não devem ter o mesmo conteúdo.

  • Bom

    "summary": "List Name",
"description": "The list to check for messages.",

  • Ruim

    "summary": "List",
"description": "List.",

RESPOSTAS

Defina seu código de sucesso usando um tipo de resposta HTTP 2xx . Não use default como sua única resposta definida, emparelhe-a com uma definição de sucesso. Se possível, liste também as respostas conhecidas 4xx/5xx .

  • Use 4xx erros de tipo quando o problema se originou no lado do cliente, aqui estão alguns exemplos:

    • 401 - The username is invalid (it can only contain lowercase letters and numbers)

  • Usar 5xx erros de tipo quando o problema se originou no lado do servidor

    • 504 - The request timed-out

  • Bom

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

Para parâmetros que aparecem em mais de uma operação, crie um parâmetro name na parameters secção em vez de definir esse parâmetro em cada operação que o usa.

  • Bom

    Neste exemplo, o parâmetro id é definido e IdInPath usado em operações GetMemberGroups e 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"
    },
  }
}

    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.

  • 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 em definições e use essa referência através de operações que tenham a mesma resposta de objeto.

  • Bom

    Neste exemplo, além de usar um parâmetro referenciado, as operações GetUser e UpdateUser fazer referência à mesma resposta UserResponse de objeto, definida uma vez na definitions secção.

    {
  "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
      }
    }
  }
}

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para fornecer comentários, vá para Enviar problemas ou obter ajuda com conectores e selecione seu tipo de feedback.

  • Last updated on