OpenAPI 2.0-schema voor Externe services

Voorbeeld 1: Eenvoudige OpenAPI-specificatie met verzoek en respons (OAS 2.0)

Hier is een voorbeeld van een API-specificatie die een ondersteund JSON-schema voor OpenAPI 2.0 bevat. De parameters (in het vet) bevatten de definitie voor de invoer accountId. De responsen daarop (ook in het vet) bevatten de definitie voor de uitvoer, die bestaat uit creditRating. Parameters en responsen laten zich vertalen in respectievelijk invoer en uitvoer, voor uw stroomacties.

{  
   "swagger":"2.0",
   "info":{  
      "description":"A service for checking credit for an account.",
      "version":"1.0.0",
      "title":"Credit Decision",
      "termsOfService":"http://swagger.io/terms/",
      "contact":{  
         "email":"apiteam@swagger.io"
      },
      "license":{  
         "name":"Apache 2.0",
         "url":"http://www.apache.org/licenses/LICENSE-2.0.html"
      }
   },
   "host":"<YourHostName>",
   "paths":{  
      "/account/lastCreditRating":{  
         "get":{  
            "summary":"Evaluates credit rating and decides what payment terms to offer.",
            "description":"",
            "consumes":[  
               "application/json",
               "application/xml"
            ],
            "produces":[  
               "application/xml",
               "application/json"
            ],
            "parameters":[{  
               "in":"body",
               "name":"body",
               "description":"Specifies input parameters to calculate payment term",
               "required":true,
               "schema":{  
                  "$ref":"#/definitions/accountId"
               }
            }],
            "responses":{  
               "200":{  
                  "description":"success",
                  "schema":{  
                     "$ref":"#/definitions/creditRating"
                  }
               },
               "405":{  
                  "description":"Invalid input"
               }
            }
         }
      }
   },
   "definitions":{  
      "accountId":{  
         "type":"object",
         "properties":{  
            "accountIdString":{  
               "type":"string"
            }
         },
         "xml":{  
            "name":"accountId"
         }
      },
      "creditRating":{  
         "type":"object",
         "properties":{  
            "creditRatingString":{  
               "type":"string"
            }
         },
         "xml":{  
            "name":"creditRating"
         }
      }
   }
}

Voorbeeld 2: Naslag voor schema benoemde objecten (OAS 2.0)

Basisset-up

• Voor de benoemde gegevens die uw organisatie gebruikt om toegang te krijgen tot het banksysteem wijst u het label Bank en de plaatshouder-URL toe, bijvoorbeeld https://api.voorbeeld.com. Gebruik voorbeeld.com, omdat u het schema erin plakt op het moment van registreren, in plaats van met een URL te verwijzen naar een API-specificatie.
• Registreer de externe service van het salarisadministratiesysteem. Gebruik de naam Bank en het benoemde gegeven Bank en kopieer en plak het volgende schema.
• De externe service van het salarisadministratiesysteem toont twee manieren om parameters te definiëren met objecttypen: een benoemd objecttype onder een blok "definitions" of een anoniem gedeclareerd objecttype inline.
  

  Opmerking De gedefinieerde of afgeleide naam van het objecttype van de parameter of een eigenschap van een objecttype moet korter zijn dan 255 tekens. Anders kan deze niet worden gebruikt in Apex of Flow Builder.

Hier is een schema in JSON-indeling met het benoemde objecttype gedefinieerd onder het blok "definitions". De naam van het objecttype telefoon is ExternalService__Bank_Phone in Apex of Flow Builder.

{
  "swagger": "2.0",
  "info": {
    "title": "bankService",
    "description": "API description in Markdown.",
    "version": "1.0.0"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "schemes": [
    "https"
  ],
  "definitions": {
    "User": {
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "phones":{
          "type":"array",
          "items":{
             "type": "object",
             "$ref": "#/definitions/Phone"
          }
        }
      }
    },
    "Phone":{
      "properties":{
        "typeofphone":{
          "type":"string"
        },
        "phone":{
          "type":"string"
        }
      }
    }
  },
  "paths": {
    "/users/{userId}": {
      "get": {
        "summary": "Returns a user by ID.",
        "parameters": [{
          "in": "path",
          "name": "userId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }
      }
    },
    "/users": {
      "post": {
        "summary": "Creates a new user.",
        "parameters": [{
          "in": "body",
          "name": "user",
          "schema": {
            "$ref": "#/definitions/User"
          }
        }],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

Hier is hetzelfde schema, maar dan opgemaakt met YAML.

swagger: '2.0'
info:
  title: bankService
  description: API description in Markdown.
  version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
  - https
definitions:
  User:
    properties:
      id:
        type: integer
      name:
        type: string
      phones:
        type: array
        items:
          type: object
          $ref: '#/definitions/Phone'
  Phone:
    properties:
      typeofphone:
        type: string
      phone:
        type: string
paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/User'
  /users:
    post:
      summary: Creates a new user.
      parameters:
        - in: body
          name: user
          schema:
            $ref: '#/definitions/User'
      responses:
        '200':
          description: OK

Voorbeeld 3: Schema met geneste anonieme objecten (OAS 2.0)

Hier is een API-specificatie met een JSON-schema met inline gedefinieerde anonieme objecttypen. De naam van het afgeleide telefoonobjecttype is ExternalService__Bank_getUsers_200_phones.

Opmerking Voor anonieme objecttypen worden door Salesforce automatisch namen van objecttypen afgeleid op basis van de externe service, bovenliggende bewerking, bewerkingsparameter, bovenliggend object en namen van objecteigenschappen. De afgeleide naam mag niet meer dan 255 tekens lang zijn. Zie "Namen van Apex klassen en ontwikkelaarsnamen van externe services" in Overwegingen bij externe services voor meer informatie.

{
  "swagger": "2.0",
  "info": {
    "title": "bankService",
    "description": "API description in Markdown.",
    "version": "1.0.0"
  },
  "host": "api.example.com",
  "basePath": "/v1",
  "schemes": [
    "https"
  ],
  "paths": {
    "/users/{userId}": {
      "get": {
        "summary": "Returns a user by ID.",
        "parameters": [{
          "in": "path",
          "name": "userId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "phones": {
                  "type":"array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "typeofphone": {
                        "type":"string"
                      },
                      "phone": {
                        "type":"string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/users": {
      "post": {
        "summary": "Creates a new user.",
        "parameters": [{
          "in": "body",
          "name": "user",
          "schema": {
          "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "phones": {
                "type":"array",
                "items": {
                  "type": "object",
                  "properties": {
                    "typeofphone": {
                      "type":"string"
                    },
                    "phone": {
                      "type":"string"
                    }
                  }
                }
              }
            }
          }
        }],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

Voorbeeld 4: Naam van Apex-objectklassen (OAS 2.0)

Hier is een API-specificatie die is geregistreerd met de externe-servicenaam BankingAutomaticTellerMachine. Maar de afgeleide objectnamen mogen niet langer zijn dan 255 lettertekens:

• ExternalService__BankingAutomaticTellerMachine_VeryImportantCustomer_phone
• ExternalService__BankingAutomaticTellerMachine_getBalanceAccountTypeChecking_OUT_200

Als u Apex of Flow Builder wilt gebruiken, moet u de schemanaam van de externe service en het schema (weergegeven in voorbeeld 5) inkorten.

Tip Als de afgeleide objectnaam langer is dan 255 tekens, probeert u een van de volgende methoden om het probleem op te lossen.

• Maak de naam van de externe service korter.
• Als het object inline wordt gedeclareerd onder een bewerkingsparameter, maakt u de naam van de bewerking korter door een operationId toe te voegen aan het schema.
• Als het object inline wordt gedeclareerd onder een eigenschap van een bovenliggend object, maakt u de naam van het bovenliggende object in het schema korter.
• Declareer het geneste object als een object op het bovenste niveau onder schema-"definitions".

{
  "swagger": "2.0",
  ...
  "paths": {
    "/balance/account/{accountId}/type/checking": {
      "get": {
        "parameters": [{
          "in": "path",
          "name": "accountId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "schema": {
              "type": "object",
              "properties": {
                "balance": {
                  "type": "integer"
                },
                "owner": {
                  "$ref": "#/definitions/VeryImportantCustomer"
                }
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "VeryImportantCustomer": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "phone": {
          "type": "object",
          "properties": {
            "number": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Voorbeeld 5: Namen van Apex-objectklassen inkorten (OAS 2.0)

Hier is een voorbeeld van een API-specificatie met een schema dat leidt tot verkorte namen. Het is geregistreerd met de verkorte naam BankAtm.

Verkort de schemanaam van de externe service naar BankAtm, de naam van het schemaobject naar VIP en voeg operationId toe als getBalance:

• ExternalService__BankAtm_VIP_phone
• ExternalService__BankAtm_getBalance_200

{
  "swagger": "2.0",
  ...
  "paths": {
    "/balance/account/{accountId}/type/checking": {
      "get": {
        "operationId": "getBalance",
        "parameters": [{
          "in": "path",
          "name": "accountId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "schema": {
              "type": "object",
              "properties": {
                "balance": {
                  "type": "integer"
                },
                "owner": {
                  "$ref": "#/definitions/VIP"
                }
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "VIP": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "phone": {
          "type": "object",
          "properties": {
            "number": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Voorbeeld 6: Inline arrays (OAS 2.0)

Dit is een voorbeeld met een inline arraydefinitie.

{
  "swagger": "2.0",
  "host": "Employees.org",
  "basePath": "/",
  ...
  "paths": {
    "/employees/{employeeId}": {
      "get": {
        "operationId": "getEmployee",
        "parameters": [{
          "in": "path",
          "name": "employeeId",
          "required": true,
          "type": "string"
        }],
        "responses": {
          "200": {
            "schema": {
              "type": "object",
              "properties": {
                "employee": {"$ref": "#/definitions/Employee"},
                "manager": {"$ref": "#/definitions/Employee"},
                "team": {
                  "type": "array",
                  "items": {"$ref": "#/definitions/Employee"}
                }
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Employee" : {
      "type": "object",
        "properties": {
          "employeeId": {"type": "string"},
          "firstName": {"type": "string"},
          "middleName": {"type": "string"},
          "lastName": {"type": "string"},
          "dateOfHire": {"type": "date"}
        }
      }
    }
  }
}

Voorbeeld 7: HTTP-headerparameters (OAS 2.0)

Zo wordt een headerparameter gedeclareerd in een OpenAPI-schema. In Apex of Flow wordt de naam "apiKey" weergegeven als een tekenreeksparameter. Wanneer u nu een tekenreekswaarde in Apex of een stroom instelt op apiKey, functioneert deze als een HTTP-parameter wanneer een aanroepverzoek wordt gedaan.

{
  "swagger": "2.0",
  "info": {
    "description": "A service for checking credit for an account.",
    "version": "1.0.0",
    "title": "Credit Decision",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "email": "apiteam@swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host": "<YourHostName>",
  "paths": {
    "/account/lastCreditRating": {
      "get": {
        "summary": "Evaluates credit rating and decides what payment terms to offer.",
        "description": "",
        "consumes": [
          "application/json",
          "application/xml"
        ],
        "produces": [
          "application/xml",
          "application/json"
        ],
        "parameters": [{
          "name": "body",
          "description": "Specifies input parameters to calculate payment term",
          "in": "body",
          "required": true,
          "schema": {
            "$ref": "#/definitions/accountId"
          }
        },{
          "name": "apiKey",
          "description": "Your API Key for calling the credit rating service",
          "in": "header",
          "type": "string"
        }],
        "responses": {
          "200": {
            "description": "success",
            "schema": {
              "$ref": "#/definitions/creditRating"
            }
          },
          "405": {
            "description": "Invalid input"
          }
        }
      }
    }
  },
  "definitions": {
    "accountId": {
      "type": "object",
      "properties": {
        "accountIdString": {
          "type": "string"
        }
      },
      "xml": {
        "name": "accountId"
      }
    },
    "creditRating": {
      "type": "object",
      "properties": {
        "creditRatingString": {
          "type": "string"
        }
      },
      "xml": {
        "name": "creditRating"
      }
    }
  }
}

Voorbeeld 8: Mediatype URL-gecodeerde formulieren (OAS 2.0)

Gegevens van verzoek- en antwoordformulieren worden gedeclareerd naast de overeenkomende consumes en produces.

{
  "swagger": "2.0",
  "info": {
    "description": "Apply here for your next mortgage",
    "version": "1.0.0",
    "title": "My Mortgage Buddy",
    "contact": {
      "email": "apiteam@swagger.io"
    }
  },
  "host": "MyMortgageBuddy.org",
  "basePath": "/mortgages",
  "paths": {
    "/apply": {
      "post": {
        "operationId": "applyMortgage",
        "consumes":  [
          "application/x-www-form-urlencoded; charset=utf-8"
        ],
        "produces":  [
          "application/x-www-form-urlencoded; charset=utf-8"
        ],
        "parameters": [{
          "description": "Desired mortgage terms",
          "name": "terms",
          "in":  "formData",
          "type": "array",
          "items": {
            "type": "integer"
          },
          "collectionFormat": "multi",
          "required": true
        },{
          "description": "Full Name",
          "name": "fullName",
          "in":  "formData",
          "type": "string",
          "required": true
        },{
          "description": "Loan amount",
          "name": "loanAmount",
          "in":  "formData",
          "type": "number",
          "required": true
        }],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "type": "object",
              "properties": {
                "formApplicationId": {
                  "type": "string"
                },
                "loanOfficerFullName": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}

Voorbeeld 9: schema-instructies allOf en additionalProperties (OAS 2.0)

Deze JSON-schemadefinitie markeert de constructen allOf voor schemaobjectsamenvatting en additionalProperties voor woordenlijstwaarden. Het voorbeeldschema wordt geregistreerd als externe service MyBank met benoemd gegeven MyBank. De registratie wordt aangeroepen door een voorbeeldstroom die de woordenlijsteigenschappen opent met een aanroepbare Apex-actie. Een Apex-eenheidstest koppelt het allemaal aan elkaar.

Het schema definieert een bankservice die klantdetails voor een klant-ID ophaalt.

• Het schemaobject Customer heeft woordenlijsteigenschappen van het type schemaobject CreditRating. In Apex heeft de klasse ExternalService.MyBank_Customer properties van het type Map<String, ExternalService_CreditRating> met de kredietbeoordelingen van de klant.
• Telefoons en e-mails hebben hun eigen eigenschappen, samen met de gemeenschappelijke eigenschappen allOf uit het schemaobject Contact.

{
  "swagger": "2.0",

  "info": {
    "title": "myBank",
    "description": "Sample Banking Service with allOf and additionalProperties schema constructs",
    "version": "1.0.0"
  },

  "host": "api.mybank.com",
  "basePath": "/v1",
  "schemes": [
    "https"
  ],

  "definitions": {
    "Customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "phones": {
          "type":"array",
          "items": {
            "$ref": "#/definitions/Phone"
          }
        },
        "emails": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Email"
          }
        }
      },
      "additionalProperties": {
        "$ref": "#/definitions/CreditRating"
      },
      "required": [
        "id",
        "name"
      ]
    },

    "Contact": {
      "type": "object",
      "properties": {
        "primary": {
          "type": "boolean"
        },
        "timeOfDay": {
          "type": "string"
        }
      },
      "required": [
        "primary"
      ]
    },
    "Phone": {
      "allOf": [
        {
          "$ref": "#/definitions/Contact"
        },
        {
          "type": "object",
          "properties": {
            "typeOfPhone": {
              "type":"string"
            },
            "phoneNumber":{
              "type":"string"
            }
          }
        }
      ]
    },
    "Email": {
      "allOf": [
        {
          "$ref": "#/definitions/Contact"
        },
        {
          "type": "object",
          "properties": {
            "email": {
              "type":"string"
            }
          }
        }
      ]
    },

    "CreditRating": {
      "type": "object",
      "properties": {
        "rating": {
          "type": "string"
        },
        "score": {
          "type": "number",
          "format": "double"
        }
      }
    }
  },

  "paths": {
    "/customers/{customerId}": {
      "get": {
        "summary": "Get the customer by ID.",
        "parameters": [{
          "in": "path",
          "name": "customerId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Customer"
            }
          }
        }
      }
    }
  }
}

Zie Voor voorbeelden 9: allOf Composition and additionalProperties Use in Flow with Apex Unit Tests als u allOf en additionalProperties wilt gebruiken.

Voorbeeld 10: instructies allOf en discriminator (OAS 2.0)

Als u een algemene uitbreidbare lijst van contactpersonen voor een klant wilt opgeven, kan de instructie discriminator worden gecombineerd met allOf om aan te geven of een contactpersoon een e-mailadres of een telefoonnummer is:

{
  "swagger": "2.0",

  "info": {
    "title": "myBank",
    "description": "Sample Banking Service with allOf and discriminator",
    "version": "1.0.0"
  },
  "host": "api.mybank.com",
  "basePath": "/v1",
  "schemes": [
    "https"
  ],
  "definitions": {
    "Customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "contacts": {
          "type":"array",
          "items": {
            "$ref": "#/definitions/Contact"
          }
        }
      },
      "required": [
        "id",
        "name"
      ]
    },

    "Contact": {
      "type": "object",
      "discriminator": "contactType",
      "properties": {
        "contactType": {
          "type": "string"
        },
        "primary": {
          "type": "boolean"
        },
        "timeOfDay": {
          "type": "string"
        }
      },
      "required": [
        "contactType",
        "primary"
      ]
    },
    "Phone": {
      "allOf": [
        {
          "$ref": "#/definitions/Contact"
        },
        {
          "type": "object",
          "properties": {
            "typeOfPhone": {
              "type":"string"
            },
            "phoneNumber":{
              "type":"string"
            }
          }
        }
      ]
    },
    "Email": {
      "allOf": [
        {
          "$ref": "#/definitions/Contact"
        },
        {
          "type": "object",
          "properties": {
            "email": {
              "type":"string"
            }
          }
        }
      ]
    }
  },

  "paths": {
    "/customers/{customerId}": {
      "get": {
        "summary": "Get the customer by ID.",
        "parameters": [{
          "in": "path",
          "name": "customerId",
          "required": true,
          "type": "integer"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Customer"
            }
          }
        }
      }
    }
  }
}

Als u samenstellings- en polymorfische OpenAPI-schemaconstructen wilt gebruiken, raadpleegt u Voor voorbeelden 10: Polymorfisering met allOf en Discriminator.

Arraydefinitie (OAS 2.0)

Externe services ondersteunt inline arraydefinities en benoemde arrays waarnaar kan worden verwezen. Lijsttypen in Externe services worden aangeduid door het objectelementtype ervan.

{
    "swagger": "2.0",
    ...
       "name": "myObjects",
       "in": "body",
       "schema": {
           "type": "array",
           "items": {
               "$ref": "#definitions/MyObject"
           }
       }
    ...
    "definitions": {
        "MyObject": {
            "type": "object",
            "properties": {...}
        }
    }
}

Declareer in Apex en Flow Builder een variabele voor de parameter myObjects door de variabele te markeren als een verzameling en het Apex elementtype ExternalService__RegistrationName_MyObject ervan te kiezen.

{
    "swagger": "2.0",
    ...
       "name": "myObjects",
       "in": "body",
       "schema": {
           "type": "array",
           "items": {
               "type": "object",
               "properties": {...}
           }
       }
    ...
    "definitions": {
        ...
    }
}

Declareer in Apex en Flow Builder een verzamelingsvariabele voor de parameter myObjects en het Apex elementtype ExternalService__RegistrationName_OperationName_IN_myObjects.

{
    "swagger": "2.0",
    ...
       "name": "myObjects",
       "in": "body",
       "schema": {
           "$ref": "#definitions/MyObjectList"
       }
    ...
    "definitions": {
        "MyObjectList": {
            "type": "array",
            "items": {
                 "$ref": "#definitions/MyObject"
            }
        }
        "MyObject": {
            "type": "object",
            "properties": {...}
        }
    }
}

Declareer in Apex en Flow Builder een verzamelingsvariabele voor de parameter myObjects en het Apex elementtype ExternalService__RegistrationName_MyObject.

{
    "swagger": "2.0",
    ...
       "name": "myObjects",
       "in": "body",
       "schema": {
           "$ref": "#definitions/MyObjectList"
       }
    ...
    "definitions": {
        "MyObjectList": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {...}
            }
        }
    }
}

Declareer in Apex en Flow Builder een verzamelingsvariabele voor de parameter myObjects en het Apex elementtype ExternalService__RegistrationName_MyObjectList.