Dela via

Följa kodstandarder

  • Artikel

Följ rekommendationer i koden när du skapar en anpassad anslutning.

API-definition

apiDefinition.swagger.json kallas även swagger och är den plats där kopplingens beteende definieras.

  • Indrag: Använd flikar med fyra blanksteg, använd inte svåra flikar.
  • Eliminera efterföljande utrymme: Efterföljande utrymme omfattar allt tomt utrymme som finns i slutet av en rad när det inte finns något annat tecken som följer den. Svåra flikar räknas som ett efterföljande blanksteg om det inte finns någonting som följer dem.

Filens struktur

Om du vill ha en läsbar swagger-definition skapar du ett API-definition med följande struktur:

  1. SwaggerOpenAPI-version (för närvarande stöds endast 2.0)
  2. Information om kopplingen (rubrik, beskrivning, status, kontakter)
  3. Värd och scheman som stöds
  4. Avsnittet Förbrukar/tillverkar
  5. Sökvägar (definitioner av åtgärder och utlösare)
  6. Definitioner (datatyper som används i åtgärder och utlösare)
  7. Parametrar (parametrar som kan användas i olika åtgärder)

Åtgärder och utlösare

Använd kamelnotation för operationId: använd versaler för alla ord (även de första). Lägg inte till bindestreck (-) eller understreck (_) för att separera ord.

  • Bra

    "operationId": "GetMessages",

  • Dålig

    "operationId": "getMessages",
"operationId": "Get-Messages",
"operationId": "Get_Messages",

Sammanfattning och beskrivning

Åtgärderna bör alltid ha en sammanfattning och en beskrivning. Sammanfattningen blir namnet på åtgärden så att den är kort och exakt. Beskrivningen bör ge mer information och avslutas med en punkt (.).

De flesta beskrivningar placeras som tips i parameterrutorna och ger en kort och meningsfull text. Beskrivningar och summeringar bör inte ha samma innehåll.

  • Bra

    "summary": "List Name",
"description": "The list to check for messages.",

  • Dålig

    "summary": "List",
"description": "List.",

SVAR

Ange framgångskoden med hjälp av en HTTP 2xx-svarstyp. Använd inte default som ditt enda definierade svar, para ihop det med en framgångsdefinition i stället. Ange även kända svar om det är 4xx/5xx möjligt.

  • Använd 4xx typfel när problemet uppstod på klientsidan. Här följer några exempel:

    • 401 - The username is invalid (it can only contain lowercase letters and numbers)

  • Använd 5xx typfel när problemet uppstod på serversidan

    • 504 - The request timed-out

  • Bra

    {
  "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."
    }
  }
}

  • Dålig

    {
  "responses": {
    "default": {
      "description": "OK",
      "schema": {
        "type": "string"
      }
    }
  }
}

Definitioner och parametrar

För parametrar som visas på mer än en åtgärd skapar du en namnparameter i avsnittet parameters i stället för att definiera parametern i varje åtgärd som använder den.

  • Bra

    I det här exemplet definieras parameter id i IdInPath och används i åtgärder GetMemberGroups och RemoveMemberFromGroup.

    {
  "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"
    },
  }
}

    Genom att använda referenser på parametrar och definitioner blir ApiDefinition mer anpassningsbar. Om beskrivningen till exempel behöver uppdateras görs den på bara en plats, i stället för i alla de åtgärder som använder den.

  • Dålig

    {
  "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
        }
      }
    }
  }
}

Skapa en definitionspost och använd referensen över åtgärder med samma objektsvar.

  • Bra

    Utöver att använda en refererad parameter refererar i detta exempel åtgärderna GetUser och UpdateUser samma objektrespons UserResponse som definieras en gång i avsnittet definitions.

    {
  "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
      }
    }
  }
}

  • Fel

    {
  "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
      }
    }
  }
}

Ge feedback

Vi uppskattar feedback på problem med vår plattform för anslutningsprogram eller förslag på nya funktioner. Om du vill lämna feedback går du till Skicka problem eller få hjälp med anslutningsprogram och väljer typ av feedback.