Document new PAP REST APIs

Includes the Pdp Group create/update API and the Deployment API.

Issue-ID: POLICY-2281
Signed-off-by: Jim Hahn <jrh3@att.com>
Change-Id: Ifde0491b029eb377c4f3083c784663df968b9d1b

5 files changed, 216 insertions, 40 deletions

diff --git a/docs/pap/pap.rst b/docs/pap/pap.rst
index d061c815..a9f6772b 100644
--- a/docs/pap/pap.rst
+++ b/docs/pap/pap.rst
@@ -142,18 +142,22 @@ Here is a sample response:
 The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full
 description of PDP group states, see the :ref:`ONAP Policy Framework Architecture <architecture-label>` page.
 
-.. swaggerv2doc:: swagger/group-pap.json
+.. swaggerv2doc:: swagger/groups-batch-pap.json
 
 This operation allows the PDP groups and subgroups to be created and updated. Many PDP groups can be created or updated
 in a single POST operation by specifying more than one PDP group in the POST operation body.
+This can be used to update the policy types supported by various subgroups.
+However, it cannot be used to update policies; that is done using one of
+the deployment requests.  Consequently, the "policy" property of this
+request will be ignored.
 
 .. note::
   Due to current limitations, if a subgroup is to be deleted from a PDP Group, then the policies must be removed from
-  the subgroup in one request, and then the subgroup deleted in a subsequent request.
+  the subgroup first.
 
 Here is a sample request:
 
-.. literalinclude:: request/group-pap-req.json
+.. literalinclude:: request/groups-batch-pap-req.json
     :language: json
 
 .. swaggerv2doc:: swagger/group-delete-pap.json
@@ -170,13 +174,32 @@ Here is a sample response:
 .. literalinclude:: response/group-query-pap-resp.json
     :language: json
 
+.. swaggerv2doc:: swagger/deployments-batch-pap.json
+
+This operation allows policies to be deployed on specific PDP groups.
+Each subgroup includes an "action" property, which is used to indicate
+that the policies are being added (POST) to the subgroup, deleted (DELETE)
+from the subgroup, or that the subgroup's entire set of policies is being
+replaced (PATCH) by a new set of policies.  As such, a subgroup may appear
+more than once in a single request, one time to delete some policies and
+another time to add new policies to the same subgroup.
+
+Here is a sample request:
+
+.. literalinclude:: request/deployment-batch-pap-req.json
+    :language: json
+
 .. swaggerv2doc:: swagger/policy-deploy-pap.json
 
-This operation allows policies to be deployed on PDP groups.
+This operation allows policies to be deployed across all relevant PDP groups.
+PAP will deploy the specified policies to all relevant subgroups.  Only the
+policies supported by a given subgroup will be deployed to that subgroup.
 
 .. note::
   The policy version is optional.  If left unspecified, then the latest version of the policy is deployed. On the other
   hand, if it is specified, it may be an integer, or it may be a fully qualified version (e.g., "3.0.2").
+  In addition, a subgroup to which a policy is being deployed must have at
+  least one PDP instance, otherwise the request will be rejected.
 
 Here is a sample request:
 
diff --git a/docs/pap/request/deployment-batch-pap-req.json b/docs/pap/request/deployment-batch-pap-req.json
new file mode 100644
index 00000000..6577bed7
--- /dev/null
+++ b/docs/pap/request/deployment-batch-pap-req.json
@@ -0,0 +1,19 @@
+{
+    "groups": [
+        {
+            "name": "SampleGroup",
+            "deploymentSubgroups": [
+                {
+                    "pdpType": "apex",
+                    "action": "POST",
+                    "policies": [
+                        {
+                            "name": "onap.controllloop.operational.apex.bbs.EastRegion",
+                            "version": "1.0.0"
+                        }
+                    ]
+                }
+            ]
+        }
+    ]
+}
diff --git a/docs/pap/request/group-pap-req.json b/docs/pap/request/groups-batch-pap-req.json
index ebe38b92..2f909413 100644
--- a/docs/pap/request/group-pap-req.json
+++ b/docs/pap/request/groups-batch-pap-req.json
@@ -14,12 +14,7 @@
                             "version": "1.0.0"
                         }
                     ],
-                    "policies": [
-                        {
-                            "name": "onap.controllloop.operational.apex.bbs.EastRegion",
-                            "version": "1.0.0"
-                        }
-                    ]
+                    "policies": []
                 },
                 {
                     "pdpType": "xacml",
diff --git a/docs/pap/swagger/deployments-batch-pap.json b/docs/pap/swagger/deployments-batch-pap.json
new file mode 100644
index 00000000..58289fb9
--- /dev/null
+++ b/docs/pap/swagger/deployments-batch-pap.json
@@ -0,0 +1,150 @@
+{
+  "swagger" : "2.0",
+  "basePath" : "/",
+  "tags" : [ {
+    "name" : "DeploymentsUpdate"
+  } ],
+  "schemes" : [ "http", "https" ],
+  "consumes" : [ "application/json", "application/yaml" ],
+  "produces" : [ "application/json", "application/yaml" ],
+  "paths" : {
+    "/policy/pap/v1/pdps/deployments/batch" : {
+      "post" : {
+        "tags" : [ "DeploymentsUpdate" ],
+        "summary" : "Updates policy deployments within specific PDP groups",
+        "description" : "Updates policy deployments within specific PDP groups, returning optional error details",
+        "operationId" : "updateGroupPolicies",
+        "produces" : [ "application/json", "application/yaml" ],
+        "parameters" : [ {
+          "name" : "X-ONAP-RequestID",
+          "in" : "header",
+          "description" : "RequestID for http transaction",
+          "required" : false,
+          "type" : "string",
+          "format" : "uuid"
+        }, {
+          "in" : "body",
+          "name" : "body",
+          "description" : "List of PDP Group Deployments",
+          "required" : true,
+          "schema" : {
+            "$ref" : "#/definitions/DeploymentGroups"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "successful operation",
+            "headers" : {
+              "X-MinorVersion" : {
+                "type" : "string",
+                "description" : "Used to request or communicate a MINOR version back from the client to the server, and from the server back to the client"
+              },
+              "X-PatchVersion" : {
+                "type" : "string",
+                "description" : "Used only to communicate a PATCH version in a response for troubleshooting purposes only, and will not be provided by the client on request"
+              },
+              "X-LatestVersion" : {
+                "type" : "string",
+                "description" : "Used only to communicate an API's latest version"
+              },
+              "X-ONAP-RequestID" : {
+                "type" : "string",
+                "format" : "uuid",
+                "description" : "Used to track REST transactions for logging purpose"
+              }
+            },
+            "schema" : {
+              "$ref" : "#/definitions/PdpGroupDeployResponse"
+            }
+          },
+          "401" : {
+            "description" : "Authentication Error"
+          },
+          "403" : {
+            "description" : "Authorization Error"
+          },
+          "500" : {
+            "description" : "Internal Server Error"
+          }
+        },
+        "security" : [ {
+          "basicAuth" : [ ]
+        } ],
+        "x-interface info" : {
+          "api-version" : "1.0.0",
+          "last-mod-release" : "Dublin"
+        }
+      }
+    }
+  },
+  "securityDefinitions" : {
+    "basicAuth" : {
+      "description" : "",
+      "type" : "basic"
+    }
+  },
+  "definitions" : {
+    "ToscaPolicyIdentifier" : {
+      "type" : "object",
+      "properties" : {
+        "name" : {
+          "type" : "string"
+        },
+        "version" : {
+          "type" : "string"
+        }
+      }
+    },
+    "PdpGroupDeployResponse" : {
+      "type" : "object",
+      "properties" : {
+        "errorDetails" : {
+          "type" : "string"
+        }
+      }
+    },
+    "DeploymentGroup" : {
+      "type" : "object",
+      "properties" : {
+        "name" : {
+          "type" : "string"
+        },
+        "deploymentSubgroups" : {
+          "type" : "array",
+          "items" : {
+            "$ref" : "#/definitions/DeploymentSubGroup"
+          }
+        }
+      }
+    },
+    "DeploymentGroups" : {
+      "type" : "object",
+      "properties" : {
+        "groups" : {
+          "type" : "array",
+          "items" : {
+            "$ref" : "#/definitions/DeploymentGroup"
+          }
+        }
+      }
+    },
+    "DeploymentSubGroup" : {
+      "type" : "object",
+      "properties" : {
+        "pdpType" : {
+          "type" : "string"
+        },
+        "action" : {
+          "type" : "string",
+          "enum" : [ "POST", "DELETE", "PATCH" ]
+        },
+        "policies" : {
+          "type" : "array",
+          "items" : {
+            "$ref" : "#/definitions/ToscaPolicyIdentifier"
+          }
+        }
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/docs/pap/swagger/group-pap.json b/docs/pap/swagger/groups-batch-pap.json
index 1298fffa..8a1899e3 100644
--- a/docs/pap/swagger/group-pap.json
+++ b/docs/pap/swagger/groups-batch-pap.json
@@ -2,19 +2,19 @@
   "swagger" : "2.0",
   "basePath" : "/",
   "tags" : [ {
-    "name" : "PdpGroupDeploy"
+    "name" : "PdpGroupUpdate"
   } ],
   "schemes" : [ "http", "https" ],
-  "consumes" : [ "application/json" ],
-  "produces" : [ "application/json" ],
+  "consumes" : [ "application/json", "application/yaml" ],
+  "produces" : [ "application/json", "application/yaml" ],
   "paths" : {
-    "/policy/pap/v1/pdps" : {
+    "/policy/pap/v1/pdps/groups/batch" : {
       "post" : {
-        "tags" : [ "PdpGroupDeploy" ],
-        "summary" : "Deploy or update PDP Groups",
-        "description" : "Deploys or updates a PDP Group, returning optional error details",
-        "operationId" : "deployGroup",
-        "produces" : [ "application/json" ],
+        "tags" : [ "PdpGroupUpdate" ],
+        "summary" : "Create or update PDP Groups",
+        "description" : "Create or update one or more PDP Groups, returning optional error details",
+        "operationId" : "createOrUpdateGroups",
+        "produces" : [ "application/json", "application/yaml" ],
         "parameters" : [ {
           "name" : "X-ONAP-RequestID",
           "in" : "header",
@@ -54,7 +54,7 @@
               }
             },
             "schema" : {
-              "$ref" : "#/definitions/PdpGroupDeployResponse"
+              "$ref" : "#/definitions/PdpGroupUpdateResponse"
             }
           },
           "401" : {
@@ -84,6 +84,14 @@
     }
   },
   "definitions" : {
+    "PdpGroupUpdateResponse" : {
+      "type" : "object",
+      "properties" : {
+        "errorDetails" : {
+          "type" : "string"
+        }
+      }
+    },
     "Pdp" : {
       "type" : "object",
       "properties" : {
@@ -202,25 +210,6 @@
           "type" : "string"
         }
       }
-    },
-    "PdpGroupDeployResponse" : {
-      "type" : "object",
-      "properties" : {
-        "errorDetails" : {
-          "type" : "string"
-        }
-      }
-    },
-    "ToscaPolicyIdentifierOptVersion" : {
-      "type" : "object",
-      "properties" : {
-        "name" : {
-          "type" : "string"
-        },
-        "version" : {
-          "type" : "string"
-        }
-      }
     }
   }
-}
+}
\ No newline at end of file