Dodržování standardů kódování
Při vytvoření vlastního konektoru dodržujte ve svém kódu tyto osvědčené postupy.
Definice rozhraní API
apiDefinition.swagger.json, neboli swagger, je místo, kde je definováno chování konektoru.
- Odsazení: Používejte měkké tabulátory se čtyřmi mezerami, nepoužívejte tvrdé tabulátory.
- Smažte mezery na konci: Za mezerou na konci řádku již nenásleduje žádný znak. Pevné tabulátory se považují za mezeru na konci řádku, pokud za nimi nic není.
Struktura souboru
Aby byla definice swaggeru čitelná, vytvořte definici rozhraní API s následující strukturou:
- Verze SwaggerOpenAPI (v současné době je podporována pouze verze 2.0)
- Informace o konektoru (název, popis, stav, kontakty)
- Hostitel a podporovaná schémata
- Sekce Spotřebovává/vytváří
- Cesty (definice akcí a triggerů)
- Definice (datové typy používané v akcích a triggerech)
- Parametry (parametry, které lze použít napříč operacemi)
Akce vs. triggery
Pro operationId použijte camelcase: počáteční písmena každého slova pište velkým (včetně prvního). Slova neoddělujte pomlčkami (-) nebo podtržítky (_).
Dobrý
"operationId": "GetMessages",Špatné
"operationId": "getMessages", "operationId": "Get-Messages", "operationId": "Get_Messages",
Shrnutí a popis
Operace by vždy měly mít shrnutí a popis. Souhrn je název operace, takže jej zachovejte krátký a přesný, zatímco popis by měl poskytnout více informací a končit tečkou (.).
Většina popisů se nachází v polích s parametry jako tipy, takže nezapomeňte zadat krátký a srozumitelný text. Popisy a souhrny nesmí mít stejný obsah.
Dobrý
"summary": "List Name", "description": "The list to check for messages.",Špatné
"summary": "List", "description": "List.",
Odpovědi respondentů
Definujte svůj kód úspěchu pomocí typu odpovědi HTTP2xx. Nepoužívejte default jako jedinou definovanou odpověď, spárujte jej s definicí úspěchu. Pokud je to možné, uveďte také seznam známých odpovědí 4xx/5xx.
Použijte typ chyb
4xx, pokud problém vznikne na straně klienta, zde je několik příkladů:401 - The username is invalid (it can only contain lowercase letters and numbers)
Použijte typ chyb
5xx, pokud problém vznikne na straně serveru.504 - The request timed-out
Dobrý
{ "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." } } }Špatné
{ "responses": { "default": { "description": "OK", "schema": { "type": "string" } } } }
Definice a parametry
U parametrů, které se zobrazují u více než jedné operace, vytvořte název parametru v sekci parameters namísto definování tohoto parametru v každé operaci, která ho používá.
Dobrý
V tomto případě je parametr
iddefinován vIdInPatha používá se v operacíchGetMemberGroupsaRemoveMemberFromGroup.{ "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" }, } }Použitím odkazů na parametry a definice lze ApiDefinition lépe udržovat. Pokud například popis potřebuje aktualizaci, bude provedena pouze na jednom místě namísto všech operací, které jej používají.
Špatné
{ "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 } } } } }
Vytvořte záznam definic a použijte tento odkaz napříč operacemi, které mají stejnou odpověď objektu.
Dobrý
V tomto příkladu, kromě použití odkazovaného parametru, operace
GetUseraUpdateUserodkazují na stejnou odpověď objektuUserResponsedefinovanou jen jednou v sekcidefinitions.{ "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 } } } }Špatné
{ "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 } } } }
Související informace
Poskytnutí názorů
Velmi si vážíme vašich názorů na problémy s naší platformou konektorů nebo nových nápadů na funkce. Chcete-li poskytnout zpětnou vazbu, přejděte do části Odeslat problémy nebo získat pomoc s konektory a vyberte typ zpětné vazby.