OpenAPI 3.0-schema voor Externe services
Deze sectie bevat OpenAPI 3.0-schemavoorbeelden voor Externe services.
Vereiste editions
| Beschikbaar in: Lightning Experience |
| Beschikbaar in: Enterprise, Performance, Unlimited en Developer Edition |
Voorbeeld 1: Eenvoudige OpenAPI-specificatie met verzoek en respons (OAS 3.0)
Hier is een voorbeeld van een API-specificatie die een ondersteund JSON-schema voor OpenAPI 3.0 bevat. De parameters bevatten de definitie voor de invoer accountId. De responsen bevatten de definitie voor de uitvoer, creditRating. Parameters, verzoeken en responsen laten zich vertalen in respectievelijk invoer en uitvoer, voor uw stroomacties.
{
"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"
}
}
}
}
}
Voorbeeld 2: Naslag voor schema benoemde objecten (OAS 3.0)
Basisset-up
- Voor de benoemde gegevens die uw organisatie gebruikt om toegang te krijgen tot het banksysteem wijst u het label Bank en de plaatshouder-URL toe, bijvoorbeeld https://api.voorbeeld.com. Gebruik voorbeeld.com omdat u het schema plakt op het moment van registratie, in plaats van een URL te gebruiken om te verwijzen naar een API-specificatie.
- Registreer de externe service van het salarisadministratiesysteem. Gebruik de naam Bank en het benoemde gegeven Bank en kopieer en plak het schema.
- De externe service van het banksysteem toont twee manieren om parameters te definiëren met objecttypen: een benoemd objecttype onder een blok "components/schema" of een anoniem gedeclareerd objecttype inline.
Opmerking De gedefinieerde of afgeleide naam van het objecttype van de parameter of een eigenschap van een objecttype moet korter zijn dan 255 tekens. Anders kan deze niet worden gebruikt in Apex of Flow Builder.
Hier is een schema met het benoemde objecttype gedefinieerd onder het blok "components/schema". De naam van het objecttype telefoon is ExternalService__Bank_Phone in Apex of 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"
}
}
}
}
}
}
Voorbeeld 3: Schema met geneste anonieme objecten (OAS 3.0)
Hier is een API-specificatie met een JSON-schema met inline gedefinieerde anonieme objecttypen. De naam van het afgeleide telefoonobjecttype is ExternalService__Bank_getUsers_200_phones.
Opmerking Voor anonieme objecttypen leidt Salesforce automatisch namen van objecttypen af. De afgeleide namen zijn gebaseerd op de namen van de externe service, de bovenliggende bewerking, de bewerkingsparameter, het bovenliggende object en de objecteigenschap. Elke afgeleide naam mag niet meer dan 255 tekens lang zijn. Zie Ondersteuning voor schemadefinities voor meer informatie.
{
"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"
}
}
}
}
}
}
Voorbeeld 4: Naam van Apex-objectklassen (OAS 3.0)
Hier is een API-specificatie die is geregistreerd met de externe-servicenaam BankingAutomaticTellerMachine. Maar de afgeleide objectnamen mogen niet langer zijn dan 255 lettertekens.
-
ExternalService__BankingAutomaticTellerMachine_VeryImportantCustomer_phone -
ExternalService__BankingAutomaticTellerMachine_getBalanceAccountTypeChecking_OUT_200
Als u Apex of Flow Builder wilt gebruiken, moet u de schemanaam van de externe service en het schema (weergegeven in voorbeeld 5) inkorten.
Tip Als de afgeleide objectnaam langer is dan 255 tekens, probeert u een van de volgende methoden om het probleem op te lossen.
- Maak de naam van de externe service korter.
- Als het object inline wordt gedeclareerd onder een bewerkingsparameter, maakt u de naam van de bewerking korter door een operationId toe te voegen aan het schema.
- Als het object inline wordt gedeclareerd onder een eigenschap van een bovenliggend object, maakt u de naam van het bovenliggende object in het schema korter.
- Declareer het geneste object als een object op het hoogste niveau onder schema "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"
}
}
}
}
}
}
}
}
Voorbeeld 5: Namen van Apex-objectklassen inkorten (OAS 3.0)
Hier is een voorbeeld van een API-specificatie met een schema dat leidt tot verkorte namen. Het is geregistreerd met de verkorte naam BankAtm.
Kort de schemanaam van de externe service in tot BankAtm, de naam van het schemaobject tot VIP en voeg operationId toe als 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"
}
}
}
}
}
}
}
}
Voorbeeld 6: Inline arrays (OAS 3.0)
Dit is een voorbeeld met een inline arraydefinitie.
{
"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"}
}
}
}
}
}
Voorbeeld 7: HTTP-headerparameters (OAS 3.0)
Zo wordt een headerparameter gedeclareerd in een OpenAPI-schema. In Apex of Flow wordt de naam "apiKey" weergegeven als een tekenreeksparameter. Wanneer u nu een tekenreekswaarde in Apex of een stroom instelt op apiKey, functioneert deze als een HTTP-parameter wanneer een aanroepverzoek wordt gedaan.
{
"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"
}
}
}
}
}
Voorbeeld 8: Mediatype URL-gecodeerde formulieren (OAS 3.0)
Aanvraag- en reactieformuliergegevens worden gedeclareerd met het mediatype 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"
}
}
}
}
}
}
}
}
}
}
}
Voorbeeld 9: schema-instructies allOf en additionalProperties (OAS 3.0)
Deze JSON-schemadefinitie markeert de constructen allOf voor schemaobjectsamenvatting en additionalProperties voor woordenlijstwaarden. Het voorbeeldschema wordt geregistreerd als externe service MyBank met benoemde referentie MyBank.
Het schema definieert een bankservice die klantdetails voor een klant-ID ophaalt.
- Het schemaobject
Customerheeft woordenlijsteigenschappen van het type schemaobjectCreditRating. In Apex heeft de klasseExternalService.MyBank_Customerpropertiesvan het typeMap<String, ExternalService_CreditRating>met de kredietbeoordelingen van de klant. PhonesenEmailshebben hun eigen eigenschappen, samen met de gemeenschappelijke eigenschappenallOfuit het schemaobjectContact.
{
"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"
}
}
}
}
}
}
Zie Voor voorbeelden 9: allOf Composition and additionalProperties Use in Flow with Apex Unit Tests als u allOf en additionalProperties wilt gebruiken.
Voorbeeld 10: instructies allOf en discriminator (OAS 3.0)
Als u een algemene uitbreidbare lijst van contactpersonen voor een klant wilt opgeven, kan de instructie discriminator worden gecombineerd met allOf om aan te geven of een contactpersoon een e-mailadres of een telefoonnummer is:
{
"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"
}
}
}
]
}
}
}
}
Als u samenstellings- en polymorfische OpenAPI-schemaconstructen wilt gebruiken, raadpleegt u Voor voorbeelden 10: Polymorfisering met allOf en Discriminator.
Voorbeeld 11: anyOf, oneOf en Discriminator-instructies (OAS 3.0)
Modeltypen voor anyOf en oneOf met onderdelen van een gemeenschappelijk schematype. anyOf en oneOf kunnen worden gecombineerd met de schema construct discriminator voor polymorfische typen.
- Sofinummer
- Het rijbewijsnummer
- De voornaam en achternaam van de klant en eventueel een tweede voornaam
In het voorbeeld kan een klant worden geïdentificeerd aan de hand van een of meer van de volgende toegestane identifiers.
Voor het schema moet zowel de voor- als achternaam van de klant worden opgegeven of een andere toegestane vorm van identificatie worden gekozen.
In dit voorbeeld wordt ook een variatie van polymorfisering voor het type Contactpersoon weergeven met oneOf en discriminator uit voorbeeld 10 met 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"
}
}
}
}
}
}
Als u samenstellings- en polymorfische OpenAPI-schemaconstructen wilt gebruiken, raadpleegt u Voor voorbeeld 11 (Open API 3.0): AnyOf, OneOf en Discriminator.
Voorbeeld 12: Callbacks (OAS3.0)
Externe services geven callback-opties op via het object callbacks van het OpenAPI 3.0-schema.
Dit is een voorbeeld van een callback voor een hypotheekaanvraagprocedure voor het fictieve bedrijf 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 acceptedVoorbeeld 13: Bestand uploaden en downloaden (OAS 3.0)
Deze specificatie bevat deze voorbeelden:
- Een PUT-bewerking voor bestandsupload: de PUT-bewerking gebruikt een parameter
keymet de locatie/bestandsnaam van het te uploaden bestand en geeft decontent-typeop. DerequestBodywordt gedefinieerd als een binaire tekenreeks en bevat de inhoud van het bestand dat wordt geüpload. - Een GET-bewerking voor het downloaden van bestanden: de GET-bewerking gebruikt een
keymet de bestandsnaam van het te downloaden bestand. De 200-respons retourneert eencontentdat is gedefinieerd als een binaire tekenreeks, en bevat de inhoud van het bestand dat wordt gedownload.
Deze specificatie verwijst naar het uploaden van een bestand naar Amazon S3, maar de specificatie kan worden gebruikt om bestanden te uploaden naar elk systeem waarvoor u een benoemd gegeven hebt geconfigureerd.
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
Zie Voor voorbeeld 13 (Open API 3.0) voor het gebruik van deze functionaliteit: Binair bestand uploaden en Voorbeeld 13 (Open API 3.0): Binair bestand downloaden.
Voorbeeld 14: Enum-parameters in query's en responsen (OAS 3.0)
Deze specificatie bevat een GET-bewerking die twee enumwaarden als parameters gebruikt:
- Een parameter
ItemStatusdie een waarde uit het ItemStatus-enum bevat. - Een parameter
ItemPrioritydie een waarde uit de ItemPriority-enum bevat.
De 200-respons retourneert een object dat de item-ID, status, prioriteit en beschrijving bevat.
{
"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"
]
}
}
}
}
Voorbeeld 15: Ondersteuning voor elk type met behulp van schema: {} (OAS 3.0)
Deze specificatie bevat een POST-methode die elke JSON-tekenreeks gebruikt. Ondersteuning van elk type is alleen beschikbaar voor organisaties die Data 360 hebben aangeleverd.
U kunt ook een gemengde structuur in uw specificatie gebruiken die getypte parameters combineert met een hoofdtekst van elk type. Definieer bijvoorbeeld getypte queryparameters, padparameters of headers voor eventmetagegevens, terwijl u de hoofdtekst van het verzoek als elk type behoudt.
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
Heeft dit artikel uw probleem opgelost?
Laat ons weten wat we kunnen doen om te verbeteren!
