Схема OpenAPI 3.0 внешних служб

Пример 1: Базовая спецификация OpenAPI с запросом и ответом (OAS 3.0)

Ниже указан пример характеристики API, содержащей поддерживаемую схему JSON для OpenAPI 3.0. Параметры содержат определение ввода 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.
• Зарегистрируйте внешнюю службу банковской системы сотрудника. Используйте имя банка и именованные регистрационные данные банка, а потом скопируйте и вставьте в схему.
• Внешняя служба банковской системы отображает два способа определения параметров с типами объектов: тип именованного объекта в блоке «компоненты/схема» или анонимно заявленный встроенный тип объекта.
  

  Примечание Имя типа объекта определенного или производного параметра или свойство с типом объекта должно содержать не более 255 символов для использования в Apex или Flow Builder.

Ниже указана схема с типом именованного объекта, определенным в блоке "components/ Schema". Имя типа объекта телефона: ExternalService__Bank_Phone в Apex или Flow Builder.

{
  "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 к схеме.
• Если объект объявлен встроенным в свойство родительского объекта, сократите имя родительского объекта в схеме.
• Объявите вложенный объект объектом верхнего уровня в схеме "компоненты/ схемы".

{
  "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: Встроенные массивы (ОАГ 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 именованных регистрационных данных.

Схема определяет банковскую службу, которая получает сведения о клиенте для кода клиента.

• Объект схемы Customer имеет свойства словаря CreditRating объекта схемы типа. В Apex ExternalService.MyBank_Customer класса использует properties свойств типа «Map<String, ExternalService_CreditRating>» с кредитным рейтингом клиента.
• Phones и Emails создают собственные свойства вместе с общими свойствами allOf из Contact. объекта схемы

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

Чтобы использовать компоновку и additionalProperties allOf, см. Примеры 9: allOf Composition и additionalProperties Use in Flow with Apex Unit Tests.

Пример 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 из примера 10 с allOf.

{
  "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)

Внешние службы определяют параметры обратного вызова посредством объекта callbacks схемы OpenAPI 3.0.

Это пример обратного вызова процесса оформления заявки на ипотеку для фиктивной компании 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: Параметры перечисления в запросах и ответах (ОАГ 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"
        ]
      }
    }
  }
}