From a6c09a2f247323d92a64cdf5793442da9a13e05c Mon Sep 17 00:00:00 2001 From: "puthuparambil.aditya" Date: Mon, 27 Jul 2020 12:09:40 +0100 Subject: [PATCH] Documentation for 'Fetch and Delete policy API with PolicyName and PolicyVersion' Issue-ID: POLICY-2585 Signed-off-by: puthuparambil.aditya Change-Id: I76c41dd139b3d41e1cadc61108682ff4bdc6f6a0 --- docs/api/api.rst | 9 ++ docs/api/swagger/policy-api.json | 281 ++++++++++++++++++++++++++++++++++++++- docs/offeredapis.rst | 14 ++ 3 files changed, 303 insertions(+), 1 deletion(-) diff --git a/docs/api/api.rst b/docs/api/api.rst index c65e35e8..990ac9e7 100644 --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -288,3 +288,12 @@ Get vFirewall Operational Policy:: Delete vFirewall Operational Policy:: curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json" + +Get all available policies:: + curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies" -H "Accept: application/json" -H "Content-Type: application/json" + +Get version 1.0.0 of vFirewall Monitoring Policy:: + curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json" + +Delete version 1.0.0 of vFirewall Monitoring Policy:: + curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json" diff --git a/docs/api/swagger/policy-api.json b/docs/api/swagger/policy-api.json index 76735751..95c73973 100644 --- a/docs/api/swagger/policy-api.json +++ b/docs/api/swagger/policy-api.json @@ -506,8 +506,287 @@ "last-mod-release" : "Dublin" } } - }, + }, + "/policy/api/v1/policies/{policyId}/versions/{policyVersion}": { + "get": { + "tags": [ + "Policy" + ], + "summary": "Retrieve specific version of a specified policy", + "description": "Returns a particular version of specified policy", + "operationId": "getSpecificPolicy", + "consumes": [ + "application/json", + "application/yaml" + ], + "produces": [ + "application/json", + "application/yaml" + ], + "parameters": [ + { + "name": "policyId", + "in": "path", + "description": "Name of policy", + "required": true, + "type": "string" + }, + { + "name": "policyVersion", + "in": "path", + "description": "Version of policy", + "required": true, + "type": "string" + }, + { + "name": "X-ONAP-RequestID", + "in": "header", + "description": "RequestID for http transaction", + "required": false, + "type": "string", + "format": "uuid" + }, + { + "name": "mode", + "in": "query", + "description": "Fetch mode for policies, BARE for bare policies (default), REFERENCED for fully referenced policies", + "required": false, + "type": "string", + "default": "bare", + "enum": [ + "BARE", + "REFERENCED" + ] + } + ], + "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/ToscaServiceTemplate" + } + }, + "401": { + "description": "Authentication Error" + }, + "403": { + "description": "Authorization Error" + }, + "404": { + "description": "Resource Not Found" + }, + "500": { + "description": "Internal Server Error" + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "x-interface info": { + "api-version": "1.0.0", + "last-mod-release": "Guilin" + } + }, + "delete": { + "tags": [ + "Policy" + ], + "summary": "Delete a particular version of a policy", + "description": "Rule: the version that has been deployed in PDP group(s) cannot be deleted", + "operationId": "deleteSpecificPolicy", + "consumes": [ + "application/json", + "application/yaml" + ], + "produces": [ + "application/json", + "application/yaml" + ], + "parameters": [ + { + "name": "policyId", + "in": "path", + "description": "ID of policy", + "required": true, + "type": "string" + }, + { + "name": "policyVersion", + "in": "path", + "description": "Version of policy", + "required": true, + "type": "string" + }, + { + "name": "X-ONAP-RequestID", + "in": "header", + "description": "RequestID for http transaction", + "required": false, + "type": "string", + "format": "uuid" + } + ], + "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/ToscaServiceTemplate" + } + }, + "401": { + "description": "Authentication Error" + }, + "403": { + "description": "Authorization Error" + }, + "404": { + "description": "Resource Not Found" + }, + "409": { + "description": "Delete Conflict, Rule Violation" + }, + "500": { + "description": "Internal Server Error" + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "x-interface info": { + "api-version": "1.0.0", + "last-mod-release": "Guilin" + } + } + }, "/policy/api/v1/policies" : { + "get": { + "tags": [ + "Policy" + ], + "summary": "Retrieve all versions of available policies", + "description": "Returns all version of available policies", + "operationId": "getPolicies", + "consumes": [ + "application/json", + "application/yaml" + ], + "produces": [ + "application/json", + "application/yaml" + ], + "parameters": [ + { + "name": "X-ONAP-RequestID", + "in": "header", + "description": "RequestID for http transaction", + "required": false, + "type": "string", + "format": "uuid" + }, + { + "name": "mode", + "in": "query", + "description": "Fetch mode for policies, BARE for bare policies (default), REFERENCED for fully referenced policies", + "required": false, + "type": "string", + "default": "bare", + "enum": [ + "BARE", + "REFERENCED" + ] + } + ], + "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/ToscaServiceTemplate" + } + }, + "401": { + "description": "Authentication Error" + }, + "403": { + "description": "Authorization Error" + }, + "404": { + "description": "Resource Not Found" + }, + "500": { + "description": "Internal Server Error" + } + }, + "security": [ + { + "basicAuth": [] + } + ], + "x-interface info": { + "api-version": "1.0.0", + "last-mod-release": "Guilin" + } + }, "post" : { "tags" : [ "Policy" ], "summary" : "Create one or more new policies", diff --git a/docs/offeredapis.rst b/docs/offeredapis.rst index 628487ce..ee90751a 100644 --- a/docs/offeredapis.rst +++ b/docs/offeredapis.rst @@ -32,3 +32,17 @@ Postman collection for `Policy Framework Lifecycle API `_ Postman collection for `Policy Framework Decision API `_ + +API Swagger Generation +---------------------- + +The standard for API definition in the RESTful API world is the OpenAPI Specification (OAS). The OAS, which is based on +the original "Swagger Specification," is being widely used in API developments. + +Execute the below curl command for swagger generation by filling in the authorization details, IP and Port information: + +.. code-block:: bash + + “curl -k --user ‘{user_id}:{password}’ https://{ip}:{port}/swagger.json” + + -- 2.16.6