Suivre les normes de codage
Lors de la création d'un connecteur personnalisé, suivez ces bonnes pratiques dans votre code.
Définition API
apiDefinition.swagger.json, également connu sous le nom de swagger, est l'endroit où le comportement du connecteur est défini.
- Indentation : utilisez des tabulations souples avec quatre espaces, n'utilisez pas de tabulations fixes.
- Supprimer l'espace de fin: L'espace de fin inclut tous les espaces situés à la fin d'une ligne lorsqu'aucun autre caractère ne le suit. Les onglets fixes comptent comme un espace de fin s'il n'y a rien qui les suit.
Structure du fichier
Pour avoir une définition de swagger lisible, créez une définition d'API avec la structure suivante :
- Version SwaggerOpenAPI (actuellement seule la version 2.0 est prise en charge)
- Informations sur le connecteur (titre, description, statut, contacts)
- Systèmes hôtes et pris en charge
- Section Consomme/Produit
- Chemins (définitions des actions et déclencheurs)
- Définitions (types de données utilisés dans les actions et les déclencheurs)
- Paramètres (Paramètres pouvant être utilisés dans toutes les opérations)
Actions et déclencheurs
Utilisez le boîtier pascal pour operationId : mettre en majuscule chaque mot (y compris le premier). N'ajoutez pas de tirets (-) ou des traits de soulignement (_) pour séparer les mots.
Convenable
"operationId": "GetMessages",Incorrect
"operationId": "getMessages", "operationId": "Get-Messages", "operationId": "Get_Messages",
Résumé et description
Les opérations doivent toujours avoir un résumé et une description. Le résumé sera le nom de l'opération donc soyez bref et précis, la description doit donner plus d'informations et se terminer par un point (.).
La plupart des descriptions sont placées comme des conseils dans les zones de paramètres, assurez-vous de fournir un texte court et significatif. Les descriptions et résumés ne devraient pas ont le même contenu.
Convenable
"summary": "List Name", "description": "The list to check for messages.",Incorrect
"summary": "List", "description": "List.",
RÉPONSES
Définissez votre code de réussite en utilisant un type de réponse HTTP 2xx. N'utilisez pas default comme seule réponse définie, associez-la plutôt à une définition de réussite. Si possible, énumérez également les réponses 4xx/5xx.
Utilisez les erreurs de type
4xxlorsque le problème est originaire du côté client, voici quelques exemples :401 - The username is invalid (it can only contain lowercase letters and numbers)
Utilisez les erreurs de type
5xxlorsque le problème provient du côté serveur504 - The request timed-out
Convenable
{ "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." } } }Incorrect
{ "responses": { "default": { "description": "OK", "schema": { "type": "string" } } } }
Définitions et paramètres
Pour les paramètres qui apparaissent sur plusieurs opérations, créez un paramètre de nom dans la section parameters au lieu de définir ce paramètre dans chaque opération qui l'utilise.
Convenable
Dans cet exemple, le paramètre
idest défini dansIdInPath, et utilisé dans les opérationsGetMemberGroupsetRemoveMemberFromGroup.{ "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" }, } }L'utilisation de références sur les paramètres et les définitions rendra l'ApiDefinition plus facile à gérer. Par exemple, si la description a besoin d'une mise à jour, cela se fera à un seul endroit, au lieu de toutes les opérations qui l'utilisent.
Incorrect
{ "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 } } } } }
Créez une entrée sur les définitions et utilisez cette référence dans les opérations qui ont la même réponse d'objet.
Convenable
Dans cet exemple, outre l’utilisation d’un paramètre référencé, les opérations
GetUseretUpdateUserréférencent la même réponse d’objetUserResponse, définie une fois dans la sectiondefinitions.{ "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 } } } }Incorrect
{ "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 } } } }
Informations associées
Fournir des commentaires
Nous apprécions grandement les commentaires sur les problèmes liés à notre plateforme de connecteurs ou les idées de nouvelles fonctionnalités. Pour fournir des commentaires, accédez à Soumettre des problèmes ou obtenir de l’aide avec les connecteurs et sélectionnez votre type de commentaire.