Esquema de OpenAPI 3.0 de Servicios externos

Ejemplo 1: Especificación de OpenAPI básica con solicitud y respuesta (OAS 3.0)

Este es un ejemplo de una especificación de API que contiene un esquema JSON compatible para OpenAPI 3.0. Los parámetros contienen la definición para la entrada de accountId. Las respuestas contienen la definición para el resultado, que es creditRating. Los parámetros, las solicitudes y las respuestas se traducen a entradas y salidas, respectivamente, para sus acciones de flujo.

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

Ejemplo 2: Referencia de esquema de objeto nombrado (OAS 3.0)

Configuración básica

• Para la credencial con nombre que su organización utiliza para acceder al sistema de banca, asigne la etiqueta Bank y la URL de marcador de posición como https://api.example.com. Utilice example.com porque pega el esquema en el momento del registro, en vez de utilizar una URL para apuntar a una especificación de API.
• Registre el servicio externo del sistema de banca de empleados. Utilice el nombre Bank y la credencial nombrada Bank y luego copie y pegue el esquema.
• El servicio externo del sistema de banca muestra dos maneras de definir parámetros con tipos de objetos: un tipo de objeto nombrado bajo un bloque "componentes/esquema" o un tipo de objeto declarado de forma anónima en línea.
  

  Nota El nombre del tipo de objeto de parámetro definido o derivado o una propiedad con un tipo de objeto, debe tener menos de 255 caracteres para su uso en Apex o Flow Builder.

Este es un esquema con el tipo de objeto nombrado definido bajo el bloque "componentes/esquema". El nombre del tipo de objeto Teléfono es ExternalService__Bank_Phone en Apex o 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"
          }
        }
      }
    }
  }
}

Ejemplo 3: Esquema de objeto anónimo anidado (OAS 3.0)

A continuación se incluye una especificación de API con un esquema JSON con tipos de objeto anónimos definidos en línea. El nombre del tipo de objeto teléfono derivado es ExternalService__Bank_getUsers_OUT_200_phones.

Nota Para tipos de objeto anónimos, Salesforce deriva automáticamente nombres de tipos de objeto. Los nombres derivados se basan en el servicio externo, la operación principal, el parámetro de operación, el objeto principal y los nombres de propiedades de objetos. Cada nombre derivado debe tener menos de 255 caracteres. Para obtener más información, consulte Compatibilidad de definición de esquema.

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

Ejemplo 4: Nomenclatura de clase de objeto de Apex (OAS 3.0)

Esta es una especificación de API registrada con el nombre del servicio externo BankingAutomaticTellerMachine. Sin embargo, los nombres de objetos derivados no deben tener más de 255 caracteres.

• ExternalService__BankingAutomaticTellerMachine_VeryImportantCustomer_phone
• ExternalService__BankingAutomaticTellerMachine_getBalanceAccountTypeChecking_OUT_200

Para utilizar Apex o Flow Builder, debe acortar el nombre del esquema de servicio externo y el esquema (mostrado en Ejemplo 5).

Sugerencia Si el nombre del objeto derivado tiene más de 255 caracteres, pruebe uno de estos métodos para resolver el problema.

• Acorte el nombre del servicio externo.
• Si el objeto se declara en línea bajo un parámetro de operación, acorte el nombre de la operación agregando un operationId al esquema.
• Si el objeto se declara en línea bajo una propiedad de objeto principal, acorte el nombre del objeto principal en el esquema.
• Declare el objeto anidado como un objeto de nivel superior bajo el esquema "componentes/esquemas".

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

Ejemplo 5: Acortar nombres de clase de objeto de Apex (OAS 3.0)

A continuación se ofrece un ejemplo de una especificación de API con un esquema que da como resultado nombres acortados. Está registrado con el nombre acortado BankAtm.

Acorte el nombre del esquema de servicio externo a BankAtm, el nombre del objeto de esquema a VIP y agregue operationId como 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"
              }
            }
          }
        }
      }
    }
  }
}

Ejemplo 6: Matrices en línea (OAS 3.0)

A continuación se incluye un ejemplo con una definición de matriz en línea.

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

Ejemplo 7: Parámetros de encabezado HTTP (OAS 3.0)

A continuación le mostramos cómo se declara un parámetro de encabezado en un esquema de OpenAPI. En Apex o Flow, el nombre “apiKey” se muestra como un parámetro de cadena. Ahora, cuando establece cualquier valor de cadena en Apex o un flujo como apiKey, funciona como un parámetro HTTP al realizar una solicitud de llamada.

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

Ejemplo 8: Tipos de medios de forma codificada con URL (OAS 3.0)

Los datos del formulario de solicitud y respuesta se declaran con application/x-www-form-urlencoded de tipo de medio.

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

Ejemplo 9: Directivas de esquema allOf y additionalProperties (OAS 3.0).

Esta definición de esquema JSON destaca las construcciones allOf para la composición del objeto de esquema y additionalProperties para valores de diccionario. El esquema de muestra se registra como servicio externo MyBank con credencial con nombre MyBank.

El esquema define un servicio de banca que obtiene detalles de clientes para un Id. de cliente.

• El objeto de esquema Customer tiene propiedades de diccionario de tipo de objeto de esquema CreditRating. En Apex, la clase ExternalService.MyBank_Customer tiene properties de propiedad de tipo Map<String, ExternalService_CreditRating> con las calificaciones crediticias del cliente.
• Phones y Emails redactan sus propias propiedades junto con las propiedades comunes allOf del objeto de esquema 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"
          }
        }
      }
    }
  }
}

Para utilizar la composición y additionalProperties de allOf, consulte Ejemplos 9: allOf Composition and additionalProperties Use in Flow with Apex Unit Tests.

Ejemplo 10: Directivas allOf y Discriminator (OAS 3.0).

Para especificar una lista ampliable general de contactos para un cliente, la directiva discriminator puede combinarse con allOf para declarar si un contacto es un correo electrónico o un número de teléfono:

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

Para utilizar composiciones y construcciones de esquemas de OpenAPI polimórficos, consulte Ejemplos 10: Polimorfismo con allOf y Discriminator.

Ejemplo 11: Directivas anyOf, oneOf y Discriminator (OAS 3.0)

Tipos de modelo de directivas de anyOf y oneOf con partes de un tipo de esquema común. anyOf y oneOf se pueden combinar con el discriminator de construcción de esquema para tipos polimórficos.

• Número de la seguridad social
• El número de carnet de conducir
• El nombre y del cliente con segundo nombre opcional

En el ejemplo, se puede identificar un cliente por uno o más de los siguientes identificadores permitidos.

El esquema impone el nombre y apellidos del cliente o selecciona cualquier otra identificación permitida.

Este ejemplo también resalta una variación del polimorfismo del tipo Contacto con oneOf y discriminator desde Ejemplo 10 con 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"
          }
        }
      }
    }
  }
}

Para utilizar construcciones de esquemas de OpenAPI polimórficas y de composición, consulte Para Ejemplo 11 (Open API 3.0): AnyOf, OneOf y Discriminator.

Ejemplo 12: Devoluciones de llamada (OAS3.0)

Servicios externos especifica opciones de devolución de llamadas a través callbacks del objeto del esquema de OpenAPI 3.0.

Este es un ejemplo de una devolución de llamada para un proceso de solicitud de hipoteca para la compañía ficticia 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

Ejemplo 13: Carga y descarga de archivos (OAS 3.0)

Esta especificación contiene estos ejemplos:

• Una operación PUT para cargar archivos: la operación PUT toma un parámetro key con la ubicación/nombre de archivo del archivo para cargar y especifica el encabezado de content-type. El requestBody se define como una cadena binaria y contiene el contenido del archivo que se está cargando.
• Una operación GET para descargar archivos: la operación GET toma un parámetro key con el nombre del archivo para descargar. La respuesta 200 devuelve un objeto content definido como una cadena binaria y contiene el contenido del archivo que se está descargando.

Esta especificación hace referencia a la carga de un archivo en Amazon S3, pero la especificación se puede utilizar para cargar archivos en cualquier sistema para el que tenga una credencial nombrada configurada.

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

Para utilizar esta función, consulte Para el ejemplo 13 (API abierta 3.0): Carga de archivos binarios y para ejemplo 13 (API abierta 3.0): Descarga de archivos binarios.

Ejemplo 14: Parámetros de número en consultas y respuestas (OEA 3.0)

Esta especificación contiene una operación GET que toma dos valores de número como parámetros:

• Parámetro de ItemStatus que contiene un valor del número ItemStatus.
• Parámetro de ItemPriority que contiene un valor del número ItemPriority.

La respuesta 200 devuelve un objeto que contiene el Id., el estado, la prioridad y la descripción del artículo.

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