Postępowanie zgodnie z standardami kodowania
Podczas tworzenia łącznika niestandardowego należy postępować zgodnie z tymi dobrymi praktykami w kodzie.
Definicja interfejsu API
Element apiDefinition.swagger.json, znany również jako swagger, to miejsce, w którym jest definiowane zachowanie łącznika.
- Wcięcie: użyj miękkich tabulatorów z czterema spacjami, nie używaj tabulatorów twardych.
- Usuń spację końcową: Spacja końcowa zawiera wszystkie białe znaki umieszczone na końcu wiersza, gdy nie ma za nimi innego znaku. Jeśli nie ma żadnych innych danych, tabulatory twarde są traktowane jako spacja końcowa.
Struktura pliku
Aby utworzyć definicję elementu swagger do odczytania, należy utworzyć definicję interfejsu API o następującej strukturze:
- Wersja interfejsu SwaggerOpenAPI (obecnie jest obsługiwana tylko wersja 2.0)
- Informacje o łączniku (tytuł, opis, stan, kontakty)
- Host i obsługiwane schematy
- Sekcja wykorzystania/tworzenia
- Ścieżki (definicje akcji i wyzwalaczy)
- Definicje (typy danych używane w akcjach i wyzwalaczach)
- Parametry (parametry używane we wszystkich operacjach)
Akcje i wyzwalacze
Użyj notacji Pascal Case dla operationId: użyj wielkich liter w każdym wyrazie (w tym w pierwszym). Nie dodawaj łączników (-) ani znaków podkreślenia (_) w celu oddzielenia wyrazów.
Dobrze
"operationId": "GetMessages",Nieprawidłowe
"operationId": "getMessages", "operationId": "Get-Messages", "operationId": "Get_Messages",
Podsumowanie i opis
Operacje powinny zawsze mieć podsumowanie i opis. Podsumowaniem będzie nazwa operacji, dlatego powinna być krótka i dokładna, a opis powinien zawierać więcej informacji i kończyć się kropką (.).
Większość opisów jest umieszczonych jako podpowiedź w polach parametrów, muszą one być krótkim i istotnym tekstem. Opisy i podsumowania nie powinny mieć tej samej zawartości.
Dobrze
"summary": "List Name", "description": "The list to check for messages.",Nieprawidłowe
"summary": "List", "description": "List.",
ODPOWIEDZI
Kod sukcesu można zdefiniować, korzystając z typu odpowiedzi HTTP 2xx. Nie należy używać elementu default jako jedynej zdefiniowanej odpowiedzi, trzeba powiązać ją z definicją sukcesu. W miarę możliwości należy także wyświetlić listę znanych odpowiedzi 4xx/5xx.
Użyj błędów typu
4xx, gdy problem pochodzi ze strony klienta. Oto kilka przykładów:401 - The username is invalid (it can only contain lowercase letters and numbers)
Błędów typu
5xxnależy użyć, gdy problem pochodzi ze strony serwera504 - The request timed-out
Dobrze
{ "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." } } }Nieprawidłowe
{ "responses": { "default": { "description": "OK", "schema": { "type": "string" } } } }
Definicje i parametry
W przypadku parametrów wyświetlanych w więcej niż jednej operacji należy utworzyć parametr nazwy w sekcji parameters, zamiast definiować ten parametr w każdej operacji, która go używa.
Dobrze
W tym przykładzie parametr
idjest definiowany w ścieżceIdInPathi używany w elementachGetMemberGroupsiRemoveMemberFromGroup.{ "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" }, } }Korzystanie z odwołań do parametrów i definicji znacznie ułatwia konserwację elementu ApiDefinition. Jeśli na przykład opis wymaga aktualizacji, zostanie on wykonana w jednym miejscu zamiast w wszystkich używających go operacji.
Nieprawidłowe
{ "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 } } } } }
Należy utworzyć wpis do definicji i użyć tego odwołania w operacjach o tej samej odpowiedzi obiektu.
Dobrze
W tym przykładzie oprócz użycia przywoływanego parametru operacje
GetUseriUpdateUserodwołują się do tej samej odpowiedzi obiektuUserResponsezdefiniowanej raz w sekcjidefinitions.{ "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 } } } }Nieprawidłowe
{ "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 } } } }
Informacje pokrewne
Przekazywanie opinii
Jesteśmy wdzięczni za opinie na temat problemów z platformą łączników oraz pomysły na nowe funkcje. Aby przekazać opinię, przejdź na stronę Przesyłanie problemów lub uzyskiwanie pomocy dotyczącej łączników i wybierz typ opinii.