外部服务 OpenAPI 2.0 模式
本部分提供了外部服务 OpenAPI 2.0 模式示例。
所需的 Edition
| 适用于：Lightning Experience |
| 适用于：Enterprise、Performance、Unlimited 和 Developer Edition |
示例 1：带请求和响应的基本 OpenAPI 规格 (OAS 2.0)
以下是包含 OpenAPI 2.0 支持的 JSON 模式的 API 规格示例。参数(粗体)包含accountId输入的定义。响应（也是粗体）包含输出的定义，即 creditRating。对于流操作，参数和响应会分别转换为输入和输出。
{
"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"
}
}
}
}示例 2：命名对象模式参考 (OAS 2.0)
基础设置
- 对于贵组织用来访问银行系统的命名凭据，请分配银行标签占位符 URL，例如 https://api.example.com。使用 example.com，因为您将在注册时粘贴 模式，而不是使用 URL 指向 API 规格。
- 注册员工银行系统的外部服务。使用银行 名称和银行 命名凭据，然后复制粘贴以下模式。
- 银行系统的外部服务显示了用对象类型定义参数的两种方式：在“定义”块下的命名对象类型或内嵌的匿名声明对象类型。
备注 定义或派生的参数对象类型名称或具有对象类型的属性必须少于 255 个字符才能在 Apex 或 Flow Builder 中使用。
以下是在 “定义”块下定义的命名对象类型的 JSON 格式模式。在 Apex 或 Flow Builder 中，电话对象类型的名称是 ExternalService__Bank_Phone。
{
"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"
}
}
}
}
}
}以下是相同的模式，但使用 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
示例 3：嵌套匿名对象模式 (OAS 2.0)
以下是带有 JSON 模式的 API 规格，以及内联定义匿名对象类型。派生的电话对象类型的名称是 ExternalService__Bank_getUsers_OUT_200_phones。
备注 对于匿名对象类型，Salesforce 会根据外部服务、父操作、操作参数、父对象和对象属性名称自动派生对象类型名称。派生名称必须少于 255 个字符。有关更多信息，请查看外部服务注意事项中的“外部服务 Apex 类名称和开发人员名称”。
{
"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"
}
}
}
}
}
}示例 4：Apex 对象类命名 (OAS 2.0)
以下是以外部服务名称 BankingAutomaticTellerMachine 注册的 API 规范。但是，派生对象名称不得超过 255 个字符：
- ExternalService__BankingAutomaticTellerMachine_VeryImportantCustomer_phone
- ExternalService__BankingAutomaticTellerMachine_getBalanceAccountTypeChecking_OUT_200
要使用 Apex 或 Flow Builder，您必须缩短外部服务模式名称和模式（如示例 5 所示）。
提示 如果派生对象名称超过 255 个字符，请尝试以下方法之一来解决该问题。
- 缩短外部服务名称。
- 如果对象是在操作参数下内嵌声明的，请通过向模式中添加 operationId 来缩短操作名称。
- 如果对象是在父对象属性下内嵌声明的，请缩短模式中的父对象名称。
- 将嵌套对象声明为模式“定义”下的顶级对象。
{
"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"
}
}
}
}
}
}
}示例 5：缩短 Apex 对象类名称 (OAS 2.0)
这里有一个 API 规格示例，它的模式导致了名称的缩短。它注册时使用的是缩短的名称 BankAtm。
将外部服务架构名称缩写为 BankAtm，将架构对象名称缩写为 VIP，并将 operationId 添加为 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"
}
}
}
}
}
}
}示例 6：内联数组 (OAS 2.0)
以下是内联数组定义的示例。
{
"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"}
}
}
}
}
}
示例 7：HTTP 标头参数 (OAS 2.0)
以下介绍了如何在 OpenAPI 模式中声明头参数。在 Apex 或 Flow 中，名称“apiKey”显示为字符串参数。现在，当您在 Apex 或流中将任何字符串值设置为 apiKey 时，它在发出标注请求时充当 HTTP 参数。
{
"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"
}
}
}
}示例 8：URL 编码形式媒体类型 (OAS 2.0)
请求和响应表单数据与匹配的consumes和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"
}
}
}
}
}
}
}
}
}
示例 9：allOf 和 additionalProperties 模式指令 (OAS 2.0)
此 JSON 模式定义突出显示了模式对象组成的构建allOf和字典值的additionalProperties。示例模式注册为具有命名凭据MyBank的外部服务MyBank。注册由示例流调用，该示例流通过 Apex 可调用操作来访问字典属性。流 Apex 单元测试将所有这些联系在一起。
该模式定义了一个银行服务，该服务获取客户 ID 的客户详细信息。
Customer模式对象具有模式对象CreditRating类型的字典属性。在 Apex 中，类ExternalService.MyBank_Customer的房地产properties类型为具有客户信用评级的Map<String, ExternalService_CreditRating>。- 电话和电子邮件与模式对象
Contact.中的常见allOf属性一起组成自己的属性
{
"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"
}
}
}
}
}
}
}要使用allOf组成和additionalProperties，见关于示例9:allOf Composition和additionalProperties 在流中使用 Apex 单元测试。
示例 10：allOf 和 Discriminator 指令 (OAS 2.0)
要为客户指定通用的可扩展联系人列表，discriminator指令可与allOf组合，以声明联系人是电子邮件还是电话号码：
{
"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"
}
}
}
}
}
}
}
要使用组件和多态 OpenAPI 模式结构，请参见对于示例 10：带 allOf 和 Discriminator 的多态性。
数组定义 (OAS 2.0)
外部服务支持内联数组定义和可引用的命名数组。外部服务中的列表类型由其对象元素类型来标识。
引用数组项定义的受支持内联数组定义
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"type": "array",
"items": {
"$ref": "#definitions/MyObject"
}
}
...
"definitions": {
"MyObject": {
"type": "object",
"properties": {...}
}
}
}在 Apex 和 Flow Builder 中，通过将变量标记为集合并选择 Apex 元素类型 ExternalService__RegistrationName_MyObject，为 myObjects 参数声明变量。
带内联数组项目定义的内联数组定义
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {...}
}
}
...
"definitions": {
...
}
}在 Apex 和 Flow Builder 中，为 myObjects 参数和 Apex 元素类型 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": {...}
}
}
}在 Apex 和 Flow Builder 中，为 myObjects 参数和 Apex 元素类型 ExternalService__RegistrationName_MyObject 声明集合变量。
带内联数组项目定义的可参照数组定义
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"$ref": "#definitions/MyObjectList"
}
...
"definitions": {
"MyObjectList": {
"type": "array",
"items": {
"type": "object",
"properties": {...}
}
}
}
}在 Apex 和 Flow Builder 中，为 myObjects 参数和 Apex 元素类型 ExternalService__RegistrationName_MyObjectList 声明集合变量。
本文章是否解决您的问题？
请与我们共享您的想法，以便我们进行改进！
