Dela via

Följa kodstandarder

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

API-definition

Den apiDefinition.swagger.json, även känd som swagger, är den plats där kopplingens beteende definieras.

  • Indrag: Använd mjuka flikar med fyra mellanslag, använd inte hårda flikar.
  • Ta bort avslutande blanksteg: Avslutande blanksteg inkluderar allt blanksteg som finns i slutet av en rad när det inte finns något annat tecken efter det. 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 pascal-hölje för operationId: Skriv varje ord med stor bokstav (inklusive det första). Lägg inte till bindestreck (-) eller understreck (_) i avgränsade 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 kommer att vara namnet på operationen så håll den 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 sammanfattningar 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

Definiera din framgångskod med hjälp av en HTTP-svarstyp 2xx . Använd default inte som ditt enda definierade svar, para ihop det med en framgångsdefinition i stället. Om möjligt bör du även lista de kända 4xx/5xx svaren.

  • Använd 4xx typfel när problemet har sitt ursprung på klientsidan, här är några exempel:

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

  • Använd 5xx typfel när problemet har sitt ursprung 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 för mer än en åtgärd skapar du en namnparameter i avsnittet parameters i stället för att definiera den här parametern i varje åtgärd som använder den.

  • Bra

    I det här exemplet definieras parametern id i IdInPath och används i åtgärderna 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

    I det här exemplet, förutom att använda en refererad parameter, refererar åtgärderna GetUser och UpdateUser refererar till samma objektsvar UserResponse, som definierats en gång i definitions avsnittet.

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

  • Dålig

    {
  "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 anslutningsplattform eller nya funktioner. Om du vill ge feedback går du till Skicka problem eller får hjälp med anslutningsprogram och väljer din feedbacktyp.

  • Last updated on