Swagger Format for PayPal Payment API

问题:

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.

回答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