Merge pull request #570 from bbiggerr/299-warning-response

[Deprecated] PayPal Payment Stage; Staged/Approved PayPal Payment Execute

Author: bbiggerr

openapi.yaml

@@ -156,6 +156,7 @@ info:
     | 200 OK  | The request was successful. |
     | 202 Accepted | The request was successful, but processing has not been completed. The response body includes a "warnings" array containing the details of incomplete processes. |
     | 204 No Content | The server successfully fulfilled the request and there is no additional content to send. |
+    | 299 Deprecated | The request was successful, but involved a deprecated endpoint. The response body includes a "warnings" array containing warning messages. |
     | 400 Bad Request | You submitted an invalid request (missing parameters, etc.). |
     | 401 Unauthorized | You failed to authenticate for this resource. |
     | 403 Forbidden | You are authenticated, but don't have permission to do this. |
@@ -1956,7 +1957,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Payment'
         '202':
-          $ref: '#/components/responses/WarningResponse'
+          $ref: '#/components/responses/AcceptedResponse'
         default:
           $ref: '#/components/responses/ErrorResponse'
       x-code-samples:
@@ -2019,15 +2020,21 @@ paths:
     x-linode-cli-command: account
     post:
       x-linode-grant: read_only
+      deprecated: true
+      x-linode-cli-skip: true
       tags:
       - Account
       summary: PayPal Payment Stage
-      description: >
+      description: |
         This begins the process of submitting a Payment via PayPal. After calling
         this endpoint, you must take the resulting `payment_id` along with
         the `payer_id` from your PayPal account and
         [POST /account/payments/paypal-execute](/docs/api/account/#stagedapproved-paypal-payment-execute)
         to complete the Payment.
+
+        **Note**: This endpoint is deprecated and may be removed in a future release. PayPal can now be
+        designated as a Payment Method for automated payments using
+        [Cloud Manager](/docs/guides/manage-billing-in-cloud-manager/#adding-a-new-payment-method).
       operationId: createPayPalPayment
       x-linode-cli-action: paypal-start
       security:
@@ -2062,6 +2069,8 @@ paths:
                         The checkout token generated for this Payment.
                       example: EC-1A2B3C4D5E6F7G8H9
                       readOnly: true
+        '299':
+          $ref: '#/components/responses/DeprecatedResponse'
         default:
           $ref: '#/components/responses/ErrorResponse'
       x-code-samples:
@@ -2085,13 +2094,19 @@ paths:
     x-linode-cli-command: account
     post:
       x-linode-grant: read_write
+      deprecated: true
+      x-linode-cli-skip: true
       tags:
       - Account
       summary: Staged/Approved PayPal Payment Execute
-      description: >
+      description: |
         Given a PaymentID and PayerID - as generated by PayPal during the
         transaction authorization process - this endpoint executes the Payment
         to capture the funds and credit your Linode Account.
+
+        **Note**: This endpoint is deprecated and may be removed in a future release. PayPal can now be
+        designated as a Payment Method for automated or manual payments using
+        [Cloud Manager](/docs/guides/manage-billing-in-cloud-manager/#adding-a-new-payment-method).
       operationId: executePayPalPayment
       x-linode-cli-action: paypal-execute
       security:
@@ -2114,7 +2129,9 @@ paths:
              schema:
                type: object
         '202':
-          $ref: '#/components/responses/WarningResponse'
+          $ref: '#/components/responses/AcceptedResponse'
+        '299':
+          $ref: '#/components/responses/DeprecatedResponse'
         default:
           $ref: '#/components/responses/ErrorResponse'
       x-code-samples:
@@ -16012,22 +16029,25 @@ components:
             'volumes:read_only': Allows access to GET your Volumes.
             'volumes:read_write': Allows access to all endpoints related to your Volumes.
   responses:
-    ErrorResponse:
-      description: Error
+    AcceptedResponse:
+      description: |
+        Accepted with warning.
+
+        A warnings array is included with the standard 200 response body.
       content:
         application/json:
           schema:
             type: object
             properties:
-              errors:
+              warnings:
                 type: array
                 items:
-                  $ref: '#/components/schemas/ErrorObject'
-    WarningResponse:
+                  $ref: '#/components/schemas/WarningObject'
+    DeprecatedResponse:
       description: |
-        Accepted with warning.
+        Request successful. This endpoint is deprecated and may be removed in a future release.
 
-        A warning object is included with the standard 200 response.
+        A warnings array is included with the standard 200 response body.
       content:
         application/json:
           schema:
@@ -16037,6 +16057,17 @@ components:
                 type: array
                 items:
                   $ref: '#/components/schemas/WarningObject'
+    ErrorResponse:
+      description: Error
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              errors:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ErrorObject'
   parameters:
     pageOffset:
       name: page
@@ -22630,7 +22661,7 @@ components:
     WarningObject:
       type: object
       description: >
-        An object for describing a single warning for incomplete processing associated with an accepted request.
+        An object for describing a single warning associated with a response.
       properties:
         title:
           type: string