Swagger Format for PayPal Payment API - json

Question

I'm new to OpenAPI and I need some help to create a basic swagger file for PayPal's payment API to create a payment from our platform. Note: OAuth is already configured.
Below is a basic swagger file but I don't know where to add the paymet request information (i.e. intent, payer, transactions etc.) into:
{
"swagger": "2.0",
"info": {
"description": "this is a payment request to through PayPal",
"title": "Swagger PayPal Payment",
"version": "1.0.0"
},
"host": "api.sandbox.paypal.com",
"basePath": "/v1/payments", //
"schemes": [ "https" ],
"paths": {
"/payment":
{
"post": {
"summary": "Creates a payment"
"description": "Creates a payment request to Paypal",
"parameters": {
},
//"intent": "sale",
//"payer":
//{
// "payment_method": "paypal"
//},
//"transactions": [
// {
// "amount": {
// "total": "9.00",
// "currency": "EUR"
// }
// }
//],
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
Testing the file on editor.swagger, I get an "OBJECT_ADDITIONAL_PROPERTIES" error on transactions, payer, and intent.

Answer 1

JSON payload is defined as a body parameter (parameter with in: body), and this parameter needs a schema that defines the JSON object properties.
You would typically define object schemas in the global definitions section and reference them using $ref.
Here is the YAML version for readability. To convert it to JSON, paste it into http://editor.swagger.io and use File > Download JSON.
swagger: "2.0"
info:
description: this is a payment request to through PayPal
title: Swagger PayPal Payment
version: "1.0.0"
host: api.sandbox.paypal.com
basePath: /v1/payments
schemes: [ https ]
paths:
/payment:
post:
summary: Creates a payment
description: Creates a payment request to Paypal
parameters:
- in: body
name: payment
required: true
schema:
$ref: "#/definitions/Payment" # <--------
responses:
"200":
description: OK
definitions:
# Request body object
Payment:
type: object
properties:
intent:
type: string
payer:
$ref: "#/definitions/Payer"
transactions:
type: array
items:
$ref: "#/definitions/Transaction"
Payer:
type: object
properties:
payment_method:
type: string
example: paypal
Transaction:
type: object
properties:
... # TODO