Add Policy Executor Open API Interface definition

- OPenApi in RTD only (for now)
- Bear authentication included in OpenApi
- Placeholder RTD page (to be completed upon feature delivery)
- For consistency (and color coding in editors) I put all Description and Example strings inside double qoutes "..."

Issue-ID: CPS-2291
Change-Id: I7f16cdce2a06cb011997005fa8b86b54c044304a
Signed-off-by: ToineSiebelink <toine.siebelink@est.tech>

3 files changed, 250 insertions, 4 deletions

diff --git a/docs/api/swagger/policy-executor/openapi.yaml b/docs/api/swagger/policy-executor/openapi.yaml
new file mode 100644
index 0000000000..868f2da810
--- /dev/null
+++ b/docs/api/swagger/policy-executor/openapi.yaml
@@ -0,0 +1,214 @@
+#  ============LICENSE_START=======================================================
+#  Copyright (C) 2024 Nordix Foundation
+#  ================================================================================
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+#  SPDX-License-Identifier: Apache-2.0
+#  ============LICENSE_END=========================================================
+
+openapi: 3.0.3
+info:
+  title: Policy Executor
+  description: "Allows NCMP to execute a policy defined by a third party implementation before proceeding with an operation"
+  version: 1.0.0
+servers:
+  - url: /policy-executor
+tags:
+  - name: policy-executor
+    description: "Execute all your policies"
+paths:
+  /policy-executor/api/v1/{action}:
+    post:
+      description: "Fire a Policy action"
+      operationId: executePolicyAction
+      parameters:
+        - $ref: '#/components/parameters/actionInPath'
+      requestBody:
+        required: true
+        description: "The action request body"
+        content:
+          application/3gpp-json-patch+json:
+            schema:
+              $ref: '#/components/schemas/PolicyExecutionRequest'
+      tags:
+        - policy-executor
+      responses:
+        '200':
+          description: "Successful policy execution"
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolicyExecutionResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      description: "Bearer token (from client that called CPS-NCMP),used by policies to identify the client"
+      scheme: bearer
+  schemas:
+    ErrorMessage:
+      type: object
+      title: Error
+      properties:
+        status:
+          type: string
+        message:
+          type: string
+        details:
+          type: string
+
+    Payload:
+      type: object
+      properties:
+        targetFdn:
+          type: string
+          description: "The complete FDN (Fully Distinguished Name) for the element to be changed"
+          example: "/Subnetwork=Ireland/MeContext=Athlone/ManagedElement=Athlone/SomeFunction=1/Cell=12"
+        cmHandleId:
+          type: string
+          description: "The CM handle ID (optional)"
+          example: "F811AF64F5146DFC545EC60B73DE948E"
+        resourceIdentifier:
+          type: string
+          description: "The resource identifier (optional)"
+          example: "ManagedElement=Athlone/SomeFunction=1/Cell=12"
+        cmChangeRequest:
+          type: object
+          description: "The content of the change to be made"
+          example: '{"Cell":[{"id":"Cell-id","attributes":{"administrativeState":"UNLOCKED"}}]}'
+      required:
+        - targetFdn
+        - cmChangeRequest
+
+    PolicyExecutionRequest:
+      type: object
+      properties:
+        payloadType:
+          type: string
+          description: "The type of payload. Currently supported options: 'CM_Write'"
+          example: "CM_Write"
+        decisionType:
+          type: string
+          description: "The type of decision. Currently supported options: 'Allow'"
+          example: "Allow"
+        payload:
+          type: array
+          items:
+            $ref: '#/components/schemas/Payload'
+      required:
+        - payloadType
+        - decisionType
+        - payload
+
+    PolicyExecutionResponse:
+      type: object
+      properties:
+        decisionId:
+          type: string
+          description: "Unique ID for the decision (for auditing purposes)"
+          example: "550e8400-e29b-41d4-a716-446655440000"
+        decision:
+          type: string
+          description: "The decision outcome. Currently supported values: 'Allow','Deny'"
+          example: "Deny"
+        message:
+          type: string
+          description: "Additional information regarding the decision outcome"
+          example: "Object locked due to recent change"
+      required:
+        - decisionId
+        - decision
+        - message
+
+  responses:
+    NotFound:
+      description: "The specified resource was not found"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 404
+            message: "Resource Not Found"
+            details: "The requested resource is not found"
+    Unauthorized:
+      description: "Unauthorized request"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 401
+            message: "Unauthorized request"
+            details: "This request is unauthorized"
+    Forbidden:
+      description: "Request forbidden"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 403
+            message: "Request Forbidden"
+            details: "This request is forbidden"
+    BadRequest:
+      description: "Bad request"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 400
+            message: "Bad Request"
+            details: "The provided request is not valid"
+
+    InternalServerError:
+      description: "Internal server error"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 500
+            message: "Internal Server Error"
+            details: "Internal server error occurred"
+
+    NotImplemented:
+      description: "Method not (yet) implemented"
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorMessage'
+          example:
+            status: 501
+            message: "Not Implemented"
+            details: "Method not implemented"
+
+  parameters:
+    actionInPath:
+      name: action
+      in: path
+      description: "The policy action. Currently supported options: 'Execute'"
+      required: true
+      schema:
+        type: string
+        example: "Execute"
+security:
+  - bearerAuth: []
diff --git a/docs/design.rst b/docs/design.rst
index af1f5abd4a..52f977a99a 100644
--- a/docs/design.rst
+++ b/docs/design.rst
@@ -60,11 +60,20 @@ and CPS-NCMP-Inventory using the drop down table in the top right:
 Consumed APIs
 =============
 
-CPS Core uses API's from the following ONAP components
+DMI-Plugin
+----------
 
-* DMI-Plugin: REST based interface which is used to provide integration
-  and allow the DMI registry API's have access to the corresponding NCMP API's within CPS Core.
-  More information on the DMI-Plugins offered APIs can be found on the :ref:`DMI-Plugin's Design Page <onap-cps-ncmp-dmi-plugin:design>`.
+DMI-Plugin is a REST based interface which is used to provide integration
+and allow the DMI registry API's have access to the corresponding NCMP API's within CPS Core.
+More information on the DMI-Plugins offered APIs can be found on the :ref:`DMI-Plugin's Design Page <onap-cps-ncmp-dmi-plugin:design>`.
+
+Policy-Executor
+---------------
+
+.. toctree::
+   :maxdepth: 1
+
+   policy-executor.rst
 
 CPS Path
 ========
diff --git a/docs/policy-executor.rst b/docs/policy-executor.rst
new file mode 100644
index 0000000000..b934a579b1
--- /dev/null
+++ b/docs/policy-executor.rst
@@ -0,0 +1,23 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2024 Nordix Foundation
+
+.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
+.. _policy_executor:
+
+
+Policy Executor
+###############
+
+.. toctree::
+   :maxdepth: 1
+
+Introduction
+============
+
+Work In Progress: This feature is not yet completed and does not affect current NCMP functionality.
+
+Consumed APIs
+-------------
+
+:download:`Policy Executor OpenApi Specification <api/swagger/policy-executor/openapi.yaml>`