Seguir los estándares de codificación
Al crear un conector personalizado, siga estas prácticas recomendadas en su código.
Definición de la API
apiDefinition.swagger.json, también conocido como swagger, es donde se define el comportamiento del conector.
- Sangría: use tabulaciones suaves con cuatro espacios, no use tabulaciones duras.
- Elimine el espacio final: el espacio final incluye todos los espacios en blanco ubicados al final de una línea cuando no hay ningún otro carácter que la siga. Las tabulaciones duras cuentan como un espacio final si no hay nada detrás de ellas.
Estructura del archivo
Para tener una definición de swagger legible, cree una definición de API con la siguiente estructura:
- Versión de SwaggerOpenAPI (actualmente solo se admite 2.0)
- Información sobre el conector (título, descripción, estado, contactos)
- Host y esquemas compatibles
- Sección consume/produce
- Rutas (definiciones de acciones y desencadenadores)
- Definiciones (tipos de datos utilizados en acciones y desencadenadores)
- Parámetros (parámetros que se pueden usar en todas las operaciones)
Acciones y desencadenadores
Use Pascal Casing para operationId: se escribe en mayúscula inicial cada palabra (incluida la primera). No agregue guiones (-) o guiones bajos (_) para separar palabras.
Bien
"operationId": "GetMessages",Incorrecto
"operationId": "getMessages", "operationId": "Get-Messages", "operationId": "Get_Messages",
Resumen y descripción
Las operaciones siempre deben tener un resumen y una descripción. El resumen será el nombre de la operación, así que sea breve y preciso, la descripción debe dar más información y terminar con un punto (.).
La mayoría de las descripciones se colocan como sugerencias en los cuadros de parámetros; asegúrese de proporcionar un texto breve y significativo. Las descripciones y los resúmenes no deben tener el mismo contenido.
Bien
"summary": "List Name", "description": "The list to check for messages.",Incorrecto
"summary": "List", "description": "List.",
RESPUESTAS
Defina su código de éxito utilizando un tipo de respuesta HTTP 2xx. No use default como su única respuesta definida, combínela con una definición de éxito en su lugar. Si es posible, enumere también las respuestas 4xx/5xx conocidas.
Use errores del tipo
4xxcuando el problema se origine en el lado del cliente, aquí hay algunos ejemplos:401 - The username is invalid (it can only contain lowercase letters and numbers)
Use errores del tipo
5xxcuando el problema se origina en el lado del servidor504 - The request timed-out
Bien
{ "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." } } }Incorrecto
{ "responses": { "default": { "description": "OK", "schema": { "type": "string" } } } }
Definiciones y parámetros
Para los parámetros que aparecen en más de una operación, cree un parámetro de nombre en la sección parameters en lugar de definir este parámetro en cada operación que lo use.
Bien
En este ejemplo, el parámetro
idse define enIdInPathy se usa en operacionesGetMemberGroupsyRemoveMemberFromGroup.{ "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" }, } }El uso de referencias en parámetros y definiciones hará que la ApiDefinition sea más fácil de mantener. Por ejemplo, si la descripción necesita una actualización, se hará en un solo lugar, en lugar de todas las operaciones que la usan.
Incorrecto
{ "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 } } } } }
Cree una entrada en las definiciones y use esa referencia en todas las operaciones que tienen la misma respuesta de objeto.
Bien
En este ejemplo, además de utilizar un parámetro referenciado, las operaciones
GetUseryUpdateUserhacen referencia a la misma respuesta de objetoUserResponsedefinida una vez en la seccióndefinitions.{ "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 } } } }Incorrecto
{ "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 } } } }
Información relacionada
Proporcionar comentarios
Agradecemos enormemente los comentarios sobre problemas con nuestra plataforma de conectores o nuevas ideas de características. Para enviar comentarios, vaya a Enviar problemas u obtener ayuda con los conectores y seleccione el tipo de comentario.