外部服務 OpenAPI 3.0 結構描述

範例 1：包含要求與回應的基本 OpenAPI 規格 (OAS 3.0)

以下是 API 規格的範例,其中包含 OpenAPI 3.0 支援的 JSON 結構描述。 參數包含 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)

基本設定

• 在您組織用來存取銀行系統的已命名認證中，指派 Bank 標籤和預留位置 URL (如 https://api.example.com)。請使用 example.com,因為您在註冊時會貼上結構描述,而非使用 URL 來指向 API 規格。
• 註冊員工銀行系統的外部服務。使用 Bank 名稱和 Bank 已命名認證,然後複製並貼至結構描述。
• 銀行系統外部服務會顯示兩個使用物件類型定義參數的方法：位於 "components/schema" 區塊下的具名物件類型,或內嵌匿名宣告的物件類型。
  

  備註 定義或衍生參數物件類型名稱，或類型為物件的內容，其長度必須少於 255 個字元才能在 Apex 或 Flow Builder 中使用。

以下是在 "components/schema" 區塊下定義具名物件類型的結構描述。電話物件類型的名稱是 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)

以下的 API 規格具有 JSON 結構描述，其中含內嵌定義的匿名物件類型。衍生的電話物件類型名稱為 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)

以下的 API 規格是以外部服務名稱 BankingAutomaticTellerMachine 註冊的。然而，衍生名稱必須少於 255 個字元。

• ExternalService__BankingAutomaticTellerMachine_VeryImportantCustomer_phone
• ExternalService__BankingAutomaticTellerMachine_getBalanceAccountTypeChecking_OUT_200

若要使用 Apex 或 Flow Builder，您必須縮短外部服務的結構描述名稱和結構描述 (顯示於範例 5)。

小秘訣 如果衍生物件名稱長於 255 個字元,請嘗試以下其中一個方法來解決問題。

• 縮短外部服務名稱。
• 如果在作業參數下宣告此物件，請將 operationId 新增至結構描述來縮短作業名稱。
• 如果在父系物件內容下內嵌宣告此物件，請在結構描述中縮短此父系物件的名稱。
• 在結構描述 "components/schemas" 下將巢狀物件宣告為最上層物件。

{
  "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 或流程中,名稱「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。

結構描述會定義銀行服務，以針對客戶識別碼取得客戶詳細資料。

• 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:在包含 Apex 單元測試的流程中使用的 allOf 組成和 additionalProperties。

範例 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 結合。

• 社會安全號碼
• 駕照號碼
• 客戶的名字和姓氏，以及選填的中間名

在此範例中,客戶可以由下列允許的一或多個識別碼來加以識別。

結構描述必須有客戶的名字和姓氏，或選擇任何其他允許的識別碼。

此範例也會醒目提示從範例 10 中含 allOf 的「連絡人」類型多型與 oneOf 和 discriminator 的變化。

{
  "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 回應會傳回包含項目識別碼、狀態、優先順序和描述的物件。

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