Seguire gli standard di codifica
Quando crei un connettore personalizzato, segui queste best practice nel codice.
Definizione API
apiDefinition.swagger.json, noto anche come swagger, è il punto in cui viene definito il comportamento del connettore.
- Rientro: usa soft tab con quattro spazi. Non usare hard tab.
- Rimuovi lo spazio finale: lo spazio finale include tutti gli spazi vuoti che si trovano alla fine di una riga, se non seguito da altri caratteri. Un hard tab è considerato come uno spazio finale se non seguito da altri caratteri.
Struttura del file
Per ottenere una definizione di swagger leggibile, crea una definizione API con la seguente struttura:
- Versione SwaggerOpenAPI (attualmente, è supportata solo la versione 2.0)
- Informazioni sul connettore (titolo, descrizione, stato, contatti)
- Schemi host e supportati
- Sezione Consumes/Produces
- Percorsi (definizioni di azioni e trigger)
- Definizioni (tipi di dati usati in azioni e trigger)
- Parametri (parametri che possono essere usati nelle operazioni)
Azioni e trigger
Usa Pascal Casing per operationId: tutte le parole in lettere maiuscole (inclusa la prima). Non aggiungere trattini (-) o caratteri di sottolineatura (_) per separare le parole.
Bene
"operationId": "GetMessages",Non valido
"operationId": "getMessages", "operationId": "Get-Messages", "operationId": "Get_Messages",
Riepilogo e descrizione
Le operazioni dovrebbero sempre essere associate a un riepilogo e una descrizione. Il riepilogo sarà il nome dell'operazione, dovrà dunque essere breve e preciso, la descrizione deve fornire maggiori informazioni e terminare con un punto (.).
La maggior parte delle descrizioni è inserita come suggerimenti nelle caselle dei parametri. Assicurati di immettere un testo breve e significativo. Descrizioni e riepiloghi non devono avere lo stesso contenuto.
Bene
"summary": "List Name", "description": "The list to check for messages.",Non valido
"summary": "List", "description": "List.",
RISPOSTE
Definisci il tuo codice di riuscita usando un tipo di risposta HTTP 2xx. Non usare default come unica risposta definita, ma abbinalo a una definizione di riuscita. Se possibile, elenca anche le risposte 4xx/5xx note.
Usa gli errori di tipo
4xxquando il problema ha avuto origine sul lato client, ecco alcuni esempi:401 - The username is invalid (it can only contain lowercase letters and numbers)
Usa gli errori di tipo
5xxquando il problema ha avuto origine sul lato server504 - The request timed-out
Bene
{ "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." } } }Non valido
{ "responses": { "default": { "description": "OK", "schema": { "type": "string" } } } }
Definizioni e parametri
Per i parametri che appaiono in più operazioni, crea un parametro name nella sezione parameters anziché definire questo parametro in ogni operazione che lo usa.
Bene
In questo esempio il parametro
idè definito inIdInPathe usato nelle operazioniGetMemberGroupseRemoveMemberFromGroup.{ "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'uso di riferimenti su parametri e definizioni renderà ApiDefinition più gestibile. Ad esempio, l'aggiornamento della descrizione eventualmente necessario verrà eseguito in un'unica posizione, anziché in tutte le operazioni che la usano.
Non valido
{ "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 } } } } }
Crea una voce sulle definizioni e usa tale riferimento in tutte le operazioni che hanno la stessa risposta di oggetto.
Bene
In questo esempio oltre a usare un parametro a cui si fa riferimento, le operazioni
GetUsereUpdateUserfanno riferimento alla stessa risposta dell'oggettoUserResponse, definita una volta nella sezionedefinitions.{ "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 } } } }Non valido
{ "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 } } } }
Informazioni correlate
Inviare commenti
L'invio da parte degli utenti di feedback sui problemi riscontrati con la piattaforma di connettori o di idee su nuove funzionalità è molto apprezzato. Per fornire un feedback, vai a Inviare problemi o ottenere assistenza per i connettori e seleziona il tipo di commenti.