外部サービス OpenAPI 3.0 スキーマ
このセクションでは、外部サービス OpenAPI 3.0 スキーマの例について説明します。
必要なエディション
| 使用可能なインターフェース: Lightning Experience |
| 使用可能なエディション: Enterprise Edition、Performance Edition、Unlimited Edition、および Developer Edition |
例 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)
基本的な設定
- 組織で銀行システムにアクセスするために使用する指定ログイン情報の場合は、Bank という表示ラベルと https://api.example.com というプレースホルダー URL を割り当てます。example.com を使用するのは、API 仕様を参照する URL を使用するのではなく、登録時にスキーマを貼り付けるためです。
- 従業員の銀行システムの外部サービスを登録します。Bank という名前と Bank という指定ログイン情報を使用し、スキーマをコピーして貼り付けます。
- 銀行システムの外部サービスは、オブジェクト種別を使用してパラメーターを定義する 2 つの方法を示しています。「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)
匿名オブジェクト種別がインラインで定義されている JSON スキーマが含まれる API 仕様を次に示します。派生した電話オブジェクト種別の名前は ExternalService__Bank_getUsers_OUT_200_phones になります。
メモ 匿名オブジェクト種別では、自動的にオブジェクト種別名が派生します。派生名は、外部サービス、親操作、操作パラメーター、親オブジェクト、オブジェクトプロパティ名に基づきます。各派生名は 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 を追加して操作名を短縮する。
- オブジェクトが親オブジェクトのプロパティでインラインで宣言されている場合、スキーマの親オブジェクト名を短縮する。
- ネストされたオブジェクトをスキーマ "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 として登録されます。
スキーマでは、顧客 ID の顧客の詳細を取得する銀行サービスを定義します。
Customerスキーマオブジェクトには、スキーマオブジェクト種別CreditRatingの辞書プロパティがあります。Apex では、クラスExternalService.MyBank_Customerには、顧客の信用等級が設定された種別Map<String, ExternalService_CreditRating>のプロパティpropertiesがあります。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と組み合わせることができます。
- 社会保障番号
- 運転免許証番号
- 顧客の姓および名 (ミドルネームは省略可能)
この例では、次の許可された識別子の 1 つまたは複数で顧客を識別できます。
このスキーマでは、姓と名の両方が必須の顧客名を選択するか、他の有効な識別子を選択できます。
さらに、次の例では、連絡先種別の多態性も強調表示されています。例 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: Callbacks (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: クエリと応答の Enum パラメーター (OAS 3.0)
この仕様には、2 つの列挙値をパラメーターとして取る 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"
]
}
}
}
}
例 15: スキーマを使用した任意の種別のサポート: {} (OAS 3.0)
この仕様には、任意の JSON 文字列を受け取る POST メソッドが含まれます。どの種別も、Data 360 がプロビジョニングされている組織でのみサポートされます。
型付きパラメーターと任意の型ボディを組み合わせた混合構造を仕様で使用することもできます。たとえば、イベントメタデータの型付きクエリパラメーター、パスパラメーター、ヘッダーを定義しながら、リクエストボディを任意の型として保持します。
openapi: 3.0.1
info:
title: Flow Any Type Test Service
description: |
Minimal OAS3 spec for any type support
version: 1.0.0
servers:
- url: https://sample.com
paths:
/test:
post:
operationId: sendTestPayload
summary: Accepts any JSON payload (anytype body)
requestBody:
required: false
content:
application/json:
schema: {}
responses:
'200':
description: Payload accepted
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: ok
この記事で問題は解決されましたか?
ご意見をお待ちしております。
