外部服务 OpenAPI 3.0 模式

示例 1：带请求和响应的基本 OpenAPI 规格 (OAS 3.0)

以下是包含 OpenAPI 3.0 支持的 JSON 模式的 API 规格示例。参数包含accountId输入的定义。响应包含输出的定义，即 creditRating。对于流操作，参数、请求和响应会分别转换为输入和输出。

{
  "openapi": "3.0.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"
    }
  },
  "servers": [
    {
      "url": "https://<YourHostName>"
    }
  ],
  "paths": {
    "/account/lastCreditRating": {
      "get": {
        "summary": "Evaluates credit rating and decides what payment terms to offer.",
        "description": "",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/accountId"
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/accountId"
              }
            }
          },
          "description": "Specifies input parameters to calculate payment term",
          "required": true
        },
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/creditRating"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/creditRating"
                }
              }
            }
          },
          "405": {
            "description": "Invalid input"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "accountId": {
        "type": "object",
        "properties": {
          "accountIdString": {
            "type": "string"
          }
        },
        "xml": {
          "name": "accountId"
        }
      },
      "creditRating": {
        "type": "object",
        "properties": {
          "creditRatingString": {
            "type": "string"
          }
        },
        "xml": {
          "name": "creditRating"
        }
      }
    }
  }
}

示例 2：命名对象模式参考 (OAS 3.0)

基础设置

• 对于贵组织用来访问银行系统的命名凭据，请分配银行标签占位符 URL，例如 https://api.example.com。使用 example.com 是因为您在注册时粘贴在模式中，而不是使用 URL 指向 API 规格。
• 注册员工银行系统的外部服务。使用银行 名称和银行 命名凭据，然后复制并粘贴到模式中。
• 银行系统的外部服务显示了使用对象类型定义参数的两种方式：“组件/模式”块下的命名对象类型或内联匿名声明的对象类型。
  

  备注 定义或派生的参数对象类型名称或具有对象类型的属性必须少于 255 个字符才能在 Apex 或 Flow Builder 中使用。

以下是在“组件/模式”块下定义的命名对象类型的模式。在 Apex 或 Flow Builder 中，电话对象类型的名称是 ExternalService__Bank_Phone。

{
  "openapi": "3.0.0",
  "info": {
    "title": "bankService",
    "description": "API description in Markdown.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
 "components": {
    "schemas": {
      "User": {
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "phones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/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,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        }
      }
    },
    "/users": {
      "post": {
        "summary": "Creates a new user.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/User"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

示例 3：嵌套匿名对象模式 (OAS 3.0)

以下是带有 JSON 模式的 API 规格，以及内联定义匿名对象类型。派生的电话对象类型的名称是 ExternalService__Bank_getUsers_OUT_200_phones。

备注 对于匿名对象类型，Salesforce 会自动派生对象类型名称。派生名称基于外部服务、父操作、操作参数、父对象和对象属性名称。每个派生名称必须少于 255 个字符。有关更多信息，请参阅模式定义支持。

{
  "openapi": "3.0.0",
  "info": {
    "title": "bankService",
    "description": "API description in Markdown.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/users/{userId}": {
      "get": {
        "summary": "Returns a user by ID.",
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "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.",
        "requestBody": {
          "content": {
            "application/json": {
              "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 3.0)

以下是以外部服务名称 BankingAutomaticTellerMachine 注册的 API 规范。但是，派生对象名称不得超过 255 个字符。

• ExternalService__BankingAutomaticTellerMachine_VeryImportantCustomer_phone
• ExternalService__BankingAutomaticTellerMachine_getBalanceAccountTypeChecking_OUT_200

要使用 Apex 或 Flow Builder，您必须缩短外部服务模式名称和模式（如示例 5 所示）。

提示 如果派生对象名称超过 255 个字符，请尝试以下方法之一来解决该问题。

• 缩短外部服务名称。
• 如果对象是在操作参数下内嵌声明的，请通过向模式中添加 operationId 来缩短操作名称。
• 如果对象是在父对象属性下内嵌声明的，请缩短模式中的父对象名称。
• 将嵌套对象声明为模式"组件/模式"下的顶级对象。

{
  "openapi": "3.0.0",
  ...
  "paths": {
    "/balance/account/{accountId}/type/checking": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "accountId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "*/*": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "balance": {
                      "type": "integer"
                    },
                    "owner": {
                      "$ref": "#/components/schemas/VeryImportantCustomer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VeryImportantCustomer": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "phone": {
            "type": "object",
            "properties": {
              "number": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

示例 5：缩短 Apex 对象类名称 (OAS 3.0)

这里有一个 API 规格示例，它的模式导致了名称的缩短。它注册时使用的是缩短的名称 BankAtm。

将外部服务模式名称缩写为 BankAtm，将模式对象名称缩写为 VIP，并将 operationId 添加为 getBalance：

• ExternalService__BankAtm_VIP_phone
• ExternalService__BankAtm_getBalance_200

{
  "openapi": "3.0.0",
  ...
  "paths": {
    "/balance/account/{accountId}/type/checking": {
      "get": {
        "operationId": "getBalance",
        "parameters": [
          {
            "in": "path",
            "name": "accountId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "balance": {
                      "type": "integer"
                    },
                    "owner": {
                      "$ref": "#/components/schemas/VIP"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VIP": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "phone": {
            "type": "object",
            "properties": {
              "number": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

示例 6：内联数组 (OAS 3.0)

以下是内联数组定义的示例。

{
  "openapi": "3.0.0",
  ...
  "paths": {
    "/employees/{employeeId}": {
      "get": {
        "operationId": "getEmployee",
        "parameters": [
          {
            "in": "path",
            "name": "employeeId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "employee": {
                      "$ref": "#/components/schemas/Employee"
                    },
                    "manager": {
                      "$ref": "#/components/schemas/Employee"
                    },
                    "team": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Employee"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Employee": {
        "type": "object",
        "properties": {
          "employeeId": {"type": "string"},
          "firstName": {"type": "string"},
          "middleName": {"type": "string"},
          "lastName": {"type": "string"},
          "dateOfHire": {"type": "date"}
        }
      }
    }
  }
}

示例 7：HTTP 标头参数 (OAS 3.0)

以下介绍了如何在 OpenAPI 模式中声明头参数。在 Apex 或 Flow 中，名称“apiKey”显示为字符串参数。现在，当您在 Apex 或流中将任何字符串值设置为 apiKey 时，它在发出标注请求时充当 HTTP 参数。

{
  "openapi": "3.0.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"
    }
  },
 "servers": [
    {
      "url": "https://<YourHostName>"
    }
  ],
  "paths": {
    "/account/lastCreditRating": {
      "get": {
        "summary": "Evaluates credit rating and decides what payment terms to offer.",
        "description": "",
        "parameters": [
          {
            "name": "apiKey",
            "description": "Your API Key for calling the credit rating service",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/accountId"
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/accountId"
              }
            }
          },
          "description": "Specifies input parameters to calculate payment term",
          "required": true
        },
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/creditRating"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/creditRating"
                }
              }
            }
          },
          "405": {
            "description": "Invalid input"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "accountId": {
        "type": "object",
        "properties": {
          "accountIdString": {
            "type": "string"
          }
        },
        "xml": {
          "name": "accountId"
        }
      },
      "creditRating": {
        "type": "object",
        "properties": {
          "creditRatingString": {
            "type": "string"
          }
        },
        "xml": {
          "name": "creditRating"
        }
      }
    }
  }
}

示例 8：URL 编码形式媒体类型 (OAS 3.0)

请求和响应表单数据使用媒体类型 application/x-www-form-urlencoded 声明。

{
  "openapi": "3.0.0",
  "info": {
    "description": "Apply here for your next mortgage",
    "version": "1.0.0",
    "title": "My Mortgage Buddy",
    "contact": {
      "email": "apiteam@swagger.io"
    }
  },
  "servers": [
    {
      "url": "https://MyMortgageBuddy.org/mortgages"
    }
  ],
  "paths": {
    "/apply": {
      "post": {
        "operationId": "applyMortgage",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded; charset=utf-8": {
              "schema": {
                "type": "object",
                "properties": {
                  "terms": {
                    "description": "Desired mortgage terms",
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "fullName": {
                    "description": "Full Name",
                    "type": "string"
                  },
                  "loanAmount": {
                    "description": "Loan amount",
                    "type": "number"
                  }
                },
                "required": [
                  "terms",
                  "fullName",
                  "loanAmount"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/x-www-form-urlencoded; charset=utf-8": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "formApplicationId": {
                      "type": "string"
                    },
                    "loanOfficerFullName": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

示例 9：allOf 和 additionalProperties 模式指令 (OAS 3.0)

此 JSON 模式定义突出显示了模式对象组成的构建allOf和字典值的additionalProperties。示例模式注册为具有命名凭据MyBank的外部服务MyBank。

该模式定义了一个银行服务，该服务获取客户 ID 的客户详细信息。

• Customer模式对象具有模式对象 CreditRating 类型的字典属性。在 Apex 中，类 ExternalService.MyBank_Customer 的房地产properties类型为具有客户信用评级的Map<String, ExternalService_CreditRating>。
• Phones 和 Emails 会与模式对象Contact.中的常见 allOf 属性一起组成自己的属性

{
  "openapi": "3.0.0",
  "info": {
    "title": "myBank",
    "description": "Sample Banking Service with allOf and additionalProperties",
    "version": "1.0.0"
  },
 "servers": [
    {
      "url": "https://api.mybank.com/v1"
    }
  ],
  "paths": {
    "/customers/{customerId}": {
      "get": {
        "summary": "Get the customer by ID.",
        "parameters": [
          {
            "in": "path",
            "name": "customerId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Customer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "phones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Phone"
            }
          },
          "emails": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Email"
            }
          }
        },
        "additionalProperties": {
          "$ref": "#/components/schemas/CreditRating"
        },
        "required": [
          "id",
          "name"
        ]
      },
      "Contact": {
        "type": "object",
        "properties": {
          "primary": {
            "type": "boolean"
          },
          "timeOfDay": {
            "type": "string"
          }
        },
        "required": [
          "primary"
        ]
      },
      "Phone": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Contact"
          },
          {
            "type": "object",
            "properties": {
              "typeOfPhone": {
                "type": "string"
              },
              "phoneNumber": {
                "type": "string"
              }
            }
          }
        ]
      },
      "Email": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Contact"
          },
          {
            "type": "object",
            "properties": {
              "email": {
                "type": "string"
              }
            }
          }
        ]
      },
      "CreditRating": {
        "type": "object",
        "properties": {
          "rating": {
            "type": "string"
          },
          "score": {
            "type": "number",
            "format": "double"
          }
        }
      }
    }
  }
}

要使用allOf组成和additionalProperties，见关于示例9:allOf Composition和additionalProperties 在流中使用 Apex 单元测试。

示例 10：allOf 和 Discriminator 指令 (OAS 3.0)

要为客户指定通用的可扩展联系人列表，discriminator指令可与allOf组合，以声明联系人是电子邮件还是电话号码：

{
  "openapi": "3.0.0",
  "info": {
    "title": "myBank",
    "description": "Sample Banking Service with allOf and discriminator",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.mybank.com/v1"
    }
  ],
  "paths": {
    "/customers/{customerId}": {
      "get": {
        "summary": "Get the customer by ID.",
        "parameters": [
          {
            "in": "path",
            "name": "customerId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Customer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "Contact": {
        "type": "object",
        "discriminator": {
          "propertyName": "contactType"
        },
        "properties": {
          "contactType": {
            "type": "string"
          },
          "primary": {
            "type": "boolean"
          },
          "timeOfDay": {
            "type": "string"
          }
        },
        "required": [
          "contactType",
          "primary"
        ]
      },
      "Phone": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Contact"
          },
          {
            "type": "object",
            "properties": {
              "typeOfPhone": {
                "type": "string"
              },
              "phoneNumber": {
                "type": "string"
              }
            }
          }
        ]
      },
      "Email": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Contact"
          },
          {
            "type": "object",
            "properties": {
              "email": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  }
}

要使用组件和多态 OpenAPI 模式结构，请参见对于示例 10：带 allOf 和 Discriminator 的多态性。

示例 11：anyOf、oneOf 和 Discriminator 指令 (OAS 3.0)

anyOf 和 oneOf 指令模型类型，包含常见模式类型的部分。anyOf 和 oneOf 可以与多态类型的模式构建discriminator组合。

• 社会保险编号
• 驾照编号
• 客户的名字和姓氏（带可选中间名）

在示例中，客户可由以下一个或多个允许的标识符来标识。

该模式要求客户的名字和姓氏，或者选择任何其他允许的标识。

此示例还突出显示了联系人类型多态性的变体，带有oneOf和discriminator，与带有allOf的示例 10 不同。

{
  "openapi": "3.0.0",
  "info": {
    "title": "myBank",
    "description": "Sample Banking Service with oneOf, anyOf and discriminator",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.mybank.com/v1"
    }
  ],
  "paths": {
    "/customers/{customerId}": {
      "get": {
        "summary": "Get the customer by ID.",
        "parameters": [
          {
            "in": "path",
            "name": "customerId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          }
        }
      }
    }
  },

  "components": {
    "schemas": {
      "Customer": {
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/SSN"
              },
              {
                "$ref": "#/components/schemas/DriversLicense"
              },
              {
                "$ref": "#/components/schemas/FullName"
              }
            ]
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          }
        },
        "required": [
          "id"
        ]
      },
      "SSN": {
        "type": "object",
        "properties": {
          "ssn": {
            "type": "string"
          }
        },
        "required": [
          "ssn"
        ]
      },
      "DriversLicense": {
        "type": "object",
        "properties": {
          "dl": {
            "type": "string"
          }
        },
        "required": [
          "dl"
        ]
      },
      "FullName": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string"
          },
          "middleName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          }
        },
        "required": [
          "firstName",
          "lastName"
        ]
      },

      "Contact": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/Phone"
          },
          {
            "$ref": "#/components/schemas/Email"
          }
        ],
        "discriminator": {
          "propertyName": "contactType"
        }
      },
      "Phone": {
        "type": "object",
        "properties": {
          "contactType": {
            "type": "string"
          },
          "typeOfPhone": {
            "type": "string"
          },
          "phoneNumber": {
            "type": "string"
          }
        }
      },
      "Email": {
        "type": "object",
        "properties": {
          "contactType": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        }
      }
    }
  }
}

要使用组件和多态 OpenAPI 模式结构，请参见对于示例 11（Open API 3.0）：AnyOf、OneOf 和 Discriminator。

示例 12：回调 (OAS3.0)

外部服务通过 OpenAPI 3.0 模式的callbacks对象指定回调选项。

这是虚构公司 Acme Mortgages 的抵押申请流程的回调示例。

openapi: 3.0.0

info:
  version: '1.0'
  title: Acme Mortgages
  description: Acme Mortgages
  
paths:
  # Example of synchronous operation GetApplication
  /applications/{applicationNumber}:
    get:
      operationId: GetApplication
      description: Get the mortgage application status and details
      parameters:
        - name: applicationNumber
          in: path
          required: true
          description: Mortgage Application Number
          schema:
            type: string
        - name: referenceId
          in: query
          description: Reference ID if applicable. Either as query or header
          schema:
            type: string
        - name: referenceId
          in: header
          description: Reference ID if applicable. Either as query or header
          schema:
            type: string
      responses:
        200:
          description: Mortgage application status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MortgageApplication'
                
  /applications:
    # Example of asynchronous operation with callback SubmitApplication
    post:
      operationId: SubmitApplication
      description: Submit a new mortgage application
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                applicant:
                  $ref: '#/components/schemas/Contact'
                object:
                  $ref: '#/components/schemas/Contact'
                statusUpdateRequest:
                  $ref: '#/components/schemas/ApplicationStatusUpdateRequest'
                callbackUrl:
                  type: object
                  properties:
                    outcome:
                      type: object
                      properties:
                        approved:
                          type: string
                        rejected:
                          type: string
                    documentation:
                      type: string
                    outcomeError:
                      type: string
      responses:
        200:
          description: Mortgage loan application submission response
          content:
            application/json:
              schema:
                type: object
                properties:
                  applicationNumber:
                    type: string
        400:
          description: Mortgage application error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MortgageApplicationError'
      callbacks:
        applicationOutcome:
          '{$request.body#/callbackUrl/outcome/approved}':
            post:
              operationId: ApplicationApproved
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/MortgageApplication'
              responses:
                200:
                  description: Approved mortgage application callback accepted
          '{$request.body#/callbackUrl/outcome/rejected}':
            post:
              operationId: ApplicationRejected
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/MortgageApplication'
              responses:
                200:
                  description: Rejected mortgage application callback accepted
        applicationDocumentation:
          '{$request.body#/callbackUrl/documentation}':
            post:
              parameters:
                - in: query
                  name: applicationNumber
                  schema:
                    type: string
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/MortgageApplicationDocumentation'
              responses:
                200:
                  description: Mortgage application documentation callback accepted
        applicationStatus_Update:
            $ref: '#/components/callbacks/ApplicationStatus_Update'
        applicationOutcomeError:
            $ref: '#/components/callbacks/applicationOutcomeError'

servers:
  - url: '/'
  
components:
  schemas:
    MortgageApplication:
      required:
        - applicationNumber
        - status
      properties:
        applicationNumber:
          type: string
        status:
          description: One of pending, approved, rejected
          type: string
        requestedAmount:
          type: number
        approvedAmount:
          type: number
        appliedOn:
          type: string
          format: date-time
        updatedOn:
          type: string
          format: date-time          
        applicant:
          $ref: '#/components/schemas/Contact'
        object:
          $ref: '#/components/schemas/Contact'

    ApplicationStatusUpdateRequest:
      description: Mortgage application status update request
      type: object
      properties:
        sendStatusUpdates:
          type: boolean
        statusUpdateCallbackUrl:
          type: string

    MortgageApplicationDocumentation:
        description: Required mortgage documentation
        type: array
        items:
          type: object
          properties:
              documentType:
                  type: string
              uploadUrl:
                  type: string
              instructions:
                  type: string 
                              
    Contact:
      type: object
      properties:
        name:
          type: string
        address:
          type: string
          
    MortgageApplicationError:
      properties:
        errorMessage:
          type: string
        applicationNumber:
          type: string

  callbacks:
    ApplicationStatus_Update:
      '{$request.body#/statusUpdateRequest/statusUpdateCallbackUrl}':
        post:
          requestBody:
            required: true
            content: 
              application/json:
                schema:
                  type: object
                  properties:
                    applicationNumber:
                      type: string
                    status:
                      type: string
                    updateMessage:
                      type: string
          responses:
            200:
                description: Mortgage application status update callback accepted
    applicationOutcomeError:
      '{$request.body#/callbackUrl/outcomeError}':
        post:
          requestBody:
            required: true
            content:
                application/json:
                  schema:
                      $ref: '#/components/schemas/MortgageApplicationError'
          responses:
            200:
                description: Mortgage application callback error accepted

示例 13：文件上传和下载 (OAS 3.0)

此规格包含这些示例：

• 文件上载的 PUT 操作 — PUT 操作使用带有要上载文件的位置/文件名的 key 参数，并指定content-type标题。该requestBody被定义为二进制字符串，并包含正在上传的文件的内容。
• 文件下载的 GET 操作 - GET 操作使用带有要下载的文件的文件名的 key 参数。200 响应返回定义为二进制字符串的content对象，并包含正在下载的文件的内容。

此规格引用将文件上载到 Amazon S3，但该规格可用于将文件上载到您已为其配置命名凭据的任何系统。

openapi: 3.0.0
info:
  title: S3 PutObject and GetObject API
  version: 1.1.0
  description: Example API for uploading and downloading files to Amazon S3 (without auth headers)

paths:
  /{key}:
    put:
      summary: Upload an object to S3 at the specified key
      description: Upload a file to the given bucket and key using HTTP PUT.
      operationId: putObject
      parameters:
        - name: key
          in: path
          required: true
          description: The key (path) of the S3 object
          schema:
            type: string
        - name: Content-Type
          in: header
          description: MIME type of the uploaded file
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
            description: Binary content of the file to upload
      responses:
        '200':
          description: Upload successful
          headers:
            ETag:
              description: The ETag of the uploaded object
              schema:
                type: string
        '400':
          description: Bad request
        '404':
          description: Bucket or key not found
        '500':
          description: Internal server error

    get:
      summary: Download an object from S3 at the specified key
      description: Download the file content from the given bucket and key using HTTP GET.
      operationId: getObject
      parameters:
        - name: key
          in: path
          required: true
          description: The key (path) of the S3 object
          schema:
            type: string
      responses:
        '200':
          description: File content returned
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '403':
          description: Access denied
        '404':
          description: Object not found
        '500':
          description: Internal server error

要使用此功能，请参阅对于示例 13（Open API 3.0）：二进制文件上传，对于示例 13（Open API 3.0）：二进制文件下载。

示例 14：查询和响应中的枚举参数 (OAS 3.0)

此规格包含 GET 操作，该操作将两个枚举值作为参数：

• 包含 ItemStatus 枚举值的 ItemStatus 参数。
• 包含 ItemPriority 枚举中的值的 ItemPriority 参数。

200 响应返回一个包含项目 ID、状态、优先级和描述的对象。

{
  "openapi": "3.0.3",
  "info": {
    "title": "Enum Examples API",
    "version": "1.0.0",
    "description": "Example API demonstrating enum parameters in queries and responses."
  },
  "servers": [
    {
      "url": "https://abc-mock-api-123456789123.herokuapp.com/"
    }
  ],
  "paths": {
    "/items": {
      "get": {
        "operationId": "getItemList",
        "summary": "Retrieve a list of items filtered by enum parameters",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ItemStatus"
            },
            "description": "Filter items by their status"
          },
          {
            "name": "priority",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ItemPriority"
            },
            "description": "Optional filter for item priority"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with list of items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ItemStatus": {
        "type": "string",
        "enum": [
          "active",
          "inactive",
          "pending",
          "archived"
        ]
      },
      "ItemPriority": {
        "type": "integer",
        "enum": [
          1,
          2,
          3,
          4,
          5
        ]
      },
      "ItemResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "status": {
            "$ref": "#/components/schemas/ItemStatus"
          },
          "priority": {
            "$ref": "#/components/schemas/ItemPriority"
          },
          "message": {
            "type": "string",
            "description": "Additional information about the item"
          }
        },
        "required": [
          "id",
          "status"
        ]
      }
    }
  }
}