Update Policy Offered APIs

Swagger documentation rendered in ReDoc webpage.
The html page is generated during the Sphinx build.
The sphinx.builders.linkcheck reports as false positives
the links that are generated dynamically, such as with the sphinxcontrib-redoc extension.

Issue-ID: POLICY-4581
Change-Id: I9b720b961332689b144d5fe9d8be82be436d1c16
Signed-off-by: lapentafd <francesco.lapenta@est.tech>

diff --git a/docs/api/api.rst b/docs/api/api.rst
index 273b875..17df746 100644 (file)
--- a/docs/api/api.rst
+++ b/docs/api/api.rst
@@ -5,8 +5,11 @@
 .. THIS IS USED INTERNALLY IN POLICY ONLY
 .. _api-label:
 
+Policy Life Cycle API
+#####################
+
 1. Policy Life Cycle API
-########################
+========================
 
 1.1 Overview
 ------------
@@ -175,22 +178,19 @@ Below is a table containing sample well-formed TOSCA compliant policies.
 
 
 2. APIs exposed
-###############
+===============
 
 2.1 Global API Table
 --------------------
 
-Below is a global API table from where swagger JSON for different types of policy design API can be downloaded.
+Below you can download the swagger YAML for Policy Framework Lifecycle API.
+You can find *Tosca Node Template Design* and *Policy Design* operations.
 
 .. csv-table::
-   :header: "API name", "Swagger JSON"
+   :header: "API name", "Swagger YAML"
    :widths: 10,5
 
-   "Healthcheck API", ":download:`link <swagger/healthcheck-api.json>`"
-   "Statistics API", ":download:`link <swagger/statistics-api.json>`"
-   "Tosca Policy Type API", ":download:`link <swagger/policytype-api.json>`"
-   "Tosca Policy API", ":download:`link <swagger/policy-api.json>`"
-   "Tosca NodeTemplate API", ":download:`link <swagger/nodetemplates-api.json>`"
+   "Policy Framework Lifecycle API", ":download:`link <https://raw.githubusercontent.com/onap/policy-api/master/main/src/main/resources/openapi/openapi.yaml>`"
 
 2.2 API Swagger
 ---------------
@@ -219,13 +219,22 @@ x-patchversion is used only to communicate a PATCH version in a response for tro
 
 x-onap-requestid is used to track REST transactions for logging purpose, as described above.
 
-.. swaggerv2doc:: swagger/healthcheck-api.json
-
-.. swaggerv2doc:: swagger/statistics-api.json
 
-.. swaggerv2doc:: swagger/policytype-api.json
+.. csv-table::
+   :header: "SWAGGER"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/policy-api.json
+   `To view the full SWAGGER click here <./local-swagger.html>`_
+    
+.. note::
+   Note that the context-path is not present in the document, because it is in the `application.yaml <https://github.com/onap/policy-api/blob/master/main/src/main/resources/application.yaml>`_ 
+   So the final url is composed by:
+   
+   .. csv-table::
+       :header: "Scheme","Host","Context-Path","Path"
+       :widths: 3,3,3,3
+    
+       "http","://<IP>:<PORT>","/policy/api/v1/","healthcheck"
 
 
 2.3 Creating MetadataSet for policy
@@ -252,9 +261,8 @@ The following sample tosca policy shows the policy metadata section that maps to
 
    "apex.decisionmaker.policy", `apex.policy.decisionmaker.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/apex.policy.decisionmaker.input.tosca.yaml>`_
 
-The following node template Apis are introduced to handle the policy metadataSets as independent entities that can be later mapped to a tosca policy during policy creation.
-
-.. swaggerv2doc:: swagger/nodetemplates-api.json
+`The node template Apis <./local-swagger.html#tag/Tosca-Node-Template-Design>`_ 
+are introduced to handle the policy metadataSets as independent entities that can be later mapped to a tosca policy during policy creation.
 
 When making a POST policy API call, the client must not only provide well-formed JSON/YAML,
 but also must conform to the TOSCA specification. For example. the "type" field for a TOSCA
@@ -336,8 +344,8 @@ Delete version 1.0.0 of vFirewall Monitoring Policy::
 
 
 3. Policy API application configuration
-#######################################
+=======================================
 
 Starting from Jakarta Release policy-api is a Springboot based microservice.
 
-The policy-api application configuration is packaged as a K8S ConfigMap object via `Policy-API OOM charts <https://gerrit.onap.org/r/gitweb?p=oom.git;a=blob;f=kubernetes/policy/components/policy-api/resources/config/apiParameters.yaml;h=c08b035d53f299fe0e08b45bd95a760283acce66;hb=refs/heads/master>`_
+The policy-api application configuration is packaged as a K8S ConfigMap object via `Policy-API OOM charts <https://raw.githubusercontent.com/onap/oom/master/kubernetes/policy/components/policy-api/resources/config/apiParameters.yaml>`_

diff --git a/docs/clamp/acm/api-protocol/acm-rest-apis.rst b/docs/clamp/acm/api-protocol/acm-rest-apis.rst
index 19c2a01..1770c75 100644 (file)
--- a/docs/clamp/acm/api-protocol/acm-rest-apis.rst
+++ b/docs/clamp/acm/api-protocol/acm-rest-apis.rst
@@ -19,7 +19,11 @@ reference to the Automation Composition Type. The incoming TOSCA is verified and
 referential integrity. On delete requests, a check is made to ensure that no Automation
 Composition Instances exist for the Automation Composition Type to be deleted.
 
-.. swaggerv2doc:: swagger/acm-comissioning.json
+.. csv-table::
+   :header: "Commissioning API"
+   :widths: 10
+
+   `ACM-R Commissioning Swagger <./local-swagger.html#tag/Automation-Composition-Definition>`_
 
 
 Instantiation API
@@ -45,7 +49,11 @@ A call to the update endpoint for a Automation Composition Instance follows the
 here: :ref:`4.1 Management of Automation Composition Instance Configurations
 <management-acm-instance-configs>`.
 
-.. swaggerv2doc:: swagger/acm-instantiation.json
+.. csv-table::
+   :header: "Instantiation API"
+   :widths: 10
+
+   `ACM-R Instantiation Swagger <./local-swagger.html#tag/Automation-Composition-Instance>`_
 
 
 Instantiation Automation Composition Instance Lifecycle Management
@@ -88,7 +96,12 @@ GUI. The API provides filtering so that specific Participants and Automation Com
 can be retrieved. In addition, the quantity of statistical information to be returned can be
 scoped.
 
-.. swaggerv2doc:: swagger/acm-monitoring.json
+.. csv-table::
+   :header: "Monitoring API"
+   :widths: 10
+
+   `ACM-R Monitoring Swagger <./local-swagger.html#tag/Participant-Monitoring>`_
+
 
 Pass Through API
 ================

diff --git a/docs/conf.py b/docs/conf.py
index 0c28118..3e04bef 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -23,7 +23,51 @@ extensions = [
     'sphinxcontrib.seqdiag',
     'sphinxcontrib.swaggerdoc',
     'sphinxcontrib.plantuml',
-    'sphinx_toolbox.collapse'
+    'sphinx_toolbox.collapse',
+    'sphinxcontrib.redoc'
+]
+
+redoc = [
+    {
+        'name': 'Policy API',
+        'page': 'api/local-swagger',
+        'spec': 'https://raw.githubusercontent.com/onap/policy-api/master/main/src/main/resources/openapi/openapi.yaml',
+        'opts': {
+            'lazy-rendering': True,
+            'suppress-warnings': True,
+            'hide-hostname': True,
+        }
+    },
+    {
+        'name': 'Policy PAP',
+        'page': 'pap/local-swagger',
+        'spec': 'https://raw.githubusercontent.com/onap/policy-pap/master/main/src/main/resources/openapi/openapi.yaml',
+        'opts': {
+            'lazy-rendering': False,
+            'suppress-warnings': True,
+            'hide-hostname': True,
+        }
+    },
+    {
+        'name': 'Policy XACML',
+        'page': 'xacml/local-swagger',
+        'spec': 'https://raw.githubusercontent.com/onap/policy-xacml-pdp/master/main/src/main/resources/openapi/openapi.yaml',
+        'opts': {
+            'lazy-rendering': False,
+            'suppress-warnings': True,
+            'hide-hostname': True,
+        }
+    },
+    {
+        'name': 'Policy ACM-R',
+        'page': 'clamp/acm/api-protocol/local-swagger',
+        'spec': 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/openapi.yaml',
+        'opts': {
+            'lazy-rendering': False,
+            'suppress-warnings': True,
+            'hide-hostname': True,
+        }
+    },
 ]
 
 #
@@ -53,5 +97,6 @@ def setup(app):
     app.add_css_file("css/ribbon.css")
 
 linkcheck_ignore = [
-  r'http://localhost:\d+/'
+  r'http://localhost:\d+/',
+  r'./local-swagger.html(.*?)'
 ]

diff --git a/docs/installation/docker.rst b/docs/installation/docker.rst
index 7f03893..78e7f90 100644 (file)
--- a/docs/installation/docker.rst
+++ b/docs/installation/docker.rst
@@ -2,6 +2,7 @@
 .. Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
+.. _docker-label:
 
 Policy Docker Installation
 --------------------------

diff --git a/docs/offeredapis.rst b/docs/offeredapis.rst
index ee90751..fb265d4 100644 (file)
--- a/docs/offeredapis.rst
+++ b/docs/offeredapis.rst
@@ -16,13 +16,19 @@ The Policy Framework supports the public APIs listed in the links below:
    api/api
    pap/pap
    xacml/decision-api
+   clamp/acm/api-protocol/acm-rest-apis
 
 Postman Environment for API Testing
 -----------------------------------
 
 The following environment file from postman can be used for testing API's. All you need to do is fill in the IP and Port information for the installation that you have created.
 
-:download:`link <PolicyAPI.postman_environment.json>`
+:download:`Postman Environment <PolicyAPI.postman_environment.json>`
+
+.. note::
+  If you are testing on a Docker Installation use *http* as **protocol**, *localhost* as **IP**, 
+  and the values set in the `export-ports.sh <https://raw.githubusercontent.com/onap/policy-docker/master/compose/export-ports.sh>`_ as **PORT**.
+  More information in: :ref:`Docker Installation <docker-label>` 
 
 Postman Collection for API Testing
 ----------------------------------
@@ -33,16 +39,32 @@ Postman collection for `Policy Framework Administration API <https://github.com/
 
 Postman collection for `Policy Framework Decision API <https://github.com/onap/policy-xacml-pdp/blob/master/postman/decision-api-collection.json>`_
 
-API Swagger Generation
-----------------------
+API Swagger
+-----------
 
 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:
+OAS 3.0 is used to describe the API contracts, and those documents are added as a source artifacts.
+
+`Swagger Specification for Policy API <https://github.com/onap/policy-api/blob/master/main/src/main/resources/openapi/openapi.yaml>`_
+
+`Swagger Specification for Policy PAP <https://github.com/onap/policy-pap/blob/master/main/src/main/resources/openapi/openapi.yaml>`_
+
+`Swagger Specification for Policy XACML-PDP <https://github.com/onap/policy-xacml-pdp/blob/master/main/src/main/resources/openapi/openapi.yaml>`_
+
+`Swagger Specification for Policy ACM-R <https://github.com/onap/policy-clamp/blob/master/runtime-acm/src/main/resources/openapi/openapi.yaml>`_
+
+`Swagger Specification for Policy DROOLS-PDP <https://github.com/onap/policy-drools-pdp/blob/master/feature-healthcheck/src/main/resources/openapi/openapi.yaml>`_
+
 
-.. code-block:: bash
+The YAML document can be imported in an web editor such as `Editor Swagger <https://editor.swagger.io/>`_ 
 
-  “curl -k --user ‘{user_id}:{password}’ https://{ip}:{port}/swagger.json”
+An "OpenApi first" approach is adopted, so starting from the Swagger document we auto-generate interfaces that are implemented in the API controllers.
 
+.. note::
+  The Swagger document can still be extracted from the code in the API that uses *Spring-Doc* dependency at the endpoint "../v3/api-docs/"
+  For Example ACM-Runtime endpoint
+  
+  ``http://<IP>:<PORT>/onap/policy/clamp/acm/v3/api-docs``
 

diff --git a/docs/pap/pap.rst b/docs/pap/pap.rst
index f46d1c7..c6da41b 100644 (file)
--- a/docs/pap/pap.rst
+++ b/docs/pap/pap.rst
@@ -3,8 +3,8 @@
 
 .. _pap-label:
 
-Policy Administration Point (PAP) Architecture
-##############################################
+Policy Administration Point API
+###############################
 
 .. contents::
     :depth: 3
@@ -12,6 +12,9 @@ Policy Administration Point (PAP) Architecture
 .. toctree::
    InternalPapPdp.rst
 
+Policy Administration Point (PAP) Architecture
+==============================================
+
 The Policy Administration Point (PAP) keeps track of PDPs, supporting the deployment of PDP groups and the deployment
 of policies across those PDP groups. Policies are created using the Policy API, but are deployed via the PAP.
 
@@ -169,9 +172,11 @@ are added in the response to each call:
    "x-patchversion", "0", "PATCH version of the API"
    "x-onap-requestid", "e1763e61-9eef-4911-b952-1be1edd9812b", "described above; used for logging purposes"
 
-:download:`Download Health Check PAP API Swagger <swagger/health-check-pap.json>`
+.. csv-table::
+   :header: "/healthcheck"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/health-check-pap.json
+   `Health Check PAP Swagger <./local-swagger.html#tag/HealthCheckRestControllerV1>`_
 
 This operation performs a health check on the PAP.
 
@@ -180,9 +185,11 @@ Here is a sample response:
 .. literalinclude:: response/health-check-pap-resp.json
     :language: json
 
-:download:`Download Consolidated Health Check PAP API Swagger <swagger/consolidated-healthcheck-pap.json>`
+.. csv-table::
+   :header: "/pdps/healthcheck"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/consolidated-healthcheck-pap.json
+   `Consolidated Health Check PAP Swagger <./local-swagger.html#tag/PolicyComponentsHealthCheckControllerV1>`_
 
 This operation performs a health check of all policy components. The response
 contains the health check result of each component. The consolidated health check
@@ -194,9 +201,11 @@ Here is a sample response:
 .. literalinclude:: response/consolidated-healthcheck-pap-resp.json
     :language: json
 
-:download:`Download Statistics PAP API Swagger <swagger/statistics-pap.json>`
+.. csv-table::
+   :header: "/statistics"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/statistics-pap.json
+   `Statistics PAP Swagger <./local-swagger.html#tag/StatisticsRestControllerV1>`_
 
 This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved.
 
@@ -209,16 +218,20 @@ Here is a sample response:
 .. literalinclude:: response/statistics-pap-resp.json
     :language: json
 
-:download:`Download State Change PAP Swagger <swagger/state-change-pap.json>`
+.. csv-table::
+   :header: "/pdps/groups/{name}"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/state-change-pap.json
+   `PDP State Change PAP Swagger <./local-swagger.html#tag/PdpGroupStateChangeControllerV1>`_
 
 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.
 
-:download:`Download Group Batch PAP API Swagger <swagger/groups-batch-pap.json>`
+.. csv-table::
+   :header: "/pdps/groups/batch"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/groups-batch-pap.json
+   `Group Batch PAP Swagger <./local-swagger.html#tag/PdpGroupCreateOrUpdateControllerV1>`_
 
 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.
@@ -249,15 +262,19 @@ Here is a sample request:
 .. literalinclude:: request/groups-batch-pap-req.json
     :language: json
 
-:download:`Download Group Delete PAP API Swagger  <swagger/group-delete-pap.json>`
+.. csv-table::
+   :header: "/pdps/groups/{name}"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/group-delete-pap.json
+   `PdpGroup Delete PAP Swagger <./local-swagger.html#tag/PdpGroupDeleteControllerV1>`_
 
 The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state.
 
-:download:`Download Group Query PAP API Swagger  <swagger/group-query-pap.json>`
+.. csv-table::
+   :header: "/pdps"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/group-query-pap.json
+   `PdpGroup Query PAP Swagger <./local-swagger.html#tag/PdpGroupQueryControllerV1>`_
 
 This operation allows the PDP groups and subgroups to be listed as well as the policies that are deployed on each PDP
 group and subgroup.
@@ -267,9 +284,11 @@ Here is a sample response:
 .. literalinclude:: response/group-query-pap-resp.json
     :language: json
 
-:download:`Download Deployments Batch PAP API Swagger  <swagger/deployments-batch-pap.json>`
+.. csv-table::
+   :header: "/pdps/deployments/batch"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/deployments-batch-pap.json
+   `Deployments Update PAP Swagger <./local-swagger.html#tag/PdpGroupDeployControllerV1>`_
 
 This operation allows policies to be deployed on specific PDP groups.
 Each subgroup includes an "action" property, which is used to indicate
@@ -289,9 +308,11 @@ Here is a sample response:
 .. literalinclude:: response/deployment-pap-resp.json
     :language: json
 
-:download:`Download Deploy PAP API Swagger  <swagger/policy-deploy-pap.json>`
+.. csv-table::
+   :header: "/pdps/policies"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/policy-deploy-pap.json
+   `Deploy PAP Swagger <./local-swagger.html#operation/deployPolicies>`_
 
 This operation allows policies to be deployed across all relevant PDP groups.
 PAP will deploy the specified policies to all relevant subgroups.  Only the
@@ -313,9 +334,11 @@ Here is a sample response:
 .. literalinclude:: response/deployment-pap-resp.json
     :language: json
 
-:download:`Download Undeploy PAP API Swagger  <swagger/policy-undeploy-pap.json>`
+.. csv-table::
+   :header: "/pdps/policies/{name}"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/policy-undeploy-pap.json
+   `Undeploy PAP Swagger <./local-swagger.html#operation/deletePolicy>`_
 
 This operation allows policies to be undeployed from PDP groups.
 
@@ -331,9 +354,12 @@ Here is a sample response:
 .. literalinclude:: response/deployment-pap-resp.json
     :language: json
 
-:download:`Download Policy Status PAP API Swagger  <swagger/policy-status-pap.json>`
+.. csv-table::
+   :header: "/policies/status"
+   :widths: 10
+
+   `All Policy Status PAP Swagger <./local-swagger.html#operation/getStatusOfAllPolicies>`_
 
-.. swaggerv2doc:: swagger/policy-status-pap.json
 
 This operation allows the status of all policies that are deployed or undeployed to be listed together.
 The result can be filtered based on pdp group name, policy name & version.
@@ -346,9 +372,11 @@ Here is a sample response:
 .. literalinclude:: response/policy-status-pap-resp.json
     :language: json
 
-:download:`Download Deployed Policy PAP API Swagger  <swagger/deployed-policy-pap.json>`
+.. csv-table::
+   :header: "/policies/deployed"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/deployed-policy-pap.json
+   `Deployed Policy Status PAP Swagger <./local-swagger.html#operation/queryAllDeployedPolicies>`_
 
 This operation allows the deployed policies to be listed together with their respective deployment status.
 The result can be filtered based on policy name & version.
@@ -358,9 +386,11 @@ Here is a sample response:
 .. literalinclude:: response/deployed-policy-pap-resp.json
     :language: json
 
-:download:`Download PDP Statistics PAP API Swagger  <swagger/pdp-statistics-pap.json>`
+.. csv-table::
+   :header: "/pdps/statistics"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/pdp-statistics-pap.json
+   `Policy Statistics PAP Swagger <./local-swagger.html#tag/StatisticsRestControllerV1>`_
 
 This operation allows the PDP statistics to be retrieved for all registered PDPs.
 The result can be filtered based on PDP group, PDP subgroup & PDP instance.
@@ -371,9 +401,11 @@ Here is a sample response:
 .. literalinclude:: response/pdp-statistics-pap-resp.json
     :language: json
 
-:download:`Download Policy Audit PAP API Swagger  <swagger/policy-audit-pap.json>`
+.. csv-table::
+   :header: "/policies/audit"
+   :widths: 10
 
-.. swaggerv2doc:: swagger/policy-audit-pap.json
+   `Policy Status PAP Swagger <./local-swagger.html#tag/PolicyAuditControllerV1>`_
 
 This operation allows the audit records of policies to be listed together.
 The result can be filtered based on pdp group name, policy name & version.

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index bd97089..f5975c8 100644 (file)
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -6,3 +6,4 @@ sphinxcontrib-swaggerdoc
 sphinxcontrib-spelling
 sphinxcontrib-plantuml
 sphinx_toolbox
+sphinxcontrib-redoc

diff --git a/docs/xacml/decision-api.rst b/docs/xacml/decision-api.rst
index 8f6a993..caf81b7 100644 (file)
--- a/docs/xacml/decision-api.rst
+++ b/docs/xacml/decision-api.rst
@@ -45,9 +45,11 @@ x-patchversion is used only to communicate a PATCH version in a response for tro
 
 x-onap-requestid is used to track REST transactions for logging purpose, as described above.
 
-:download:`Download the Decision API Swagger <swagger.json>`
+.. csv-table::
+   :header: "Swagger"
+   :widths: 10
 
-.. swaggerv2doc:: swagger.json
+   `Decision API Swagger <./local-swagger.html>`_
 
 
 End of Document