Add documentation for PMS

Change-Id: I4b496142f1c21edd9a044b76d35592ba2ec8c083
Issue-ID: CCSDK-2833
Signed-off-by: elinuxhenrik <henrik.b.andersson@est.tech>

2 files changed, 848 insertions, 3 deletions

diff --git a/docs/offeredapis/offeredapis.rst b/docs/offeredapis/offeredapis.rst
index 7d32acb4..c3a7c95f 100644
--- a/docs/offeredapis/offeredapis.rst
+++ b/docs/offeredapis/offeredapis.rst
@@ -68,12 +68,15 @@ API Table
 .. |swagger-icon| image:: ../media/swagger.png
                   :width: 40px
 
+.. |yaml-icon| image:: ../media/yaml_logo.png
+                  :width: 40px
+
 
 .. csv-table::
-   :header: "API name", "|swagger-icon|"
-   :widths: 10,5
+   :header: "API name", "|swagger-icon|", "|yaml-icon|"
+   :widths: 10,5, 5
 
-   "PMS API", ":download:`link <./swagger/pms-api.json>`"
+   "PMS API", ":download:`link <./swagger/pms-api.json>`", ":download:`link <./swagger/pms-api.yaml>`"
 
 
 .. _pms_api:
diff --git a/docs/offeredapis/swagger/pms-api.yaml b/docs/offeredapis/swagger/pms-api.yaml
new file mode 100644
index 00000000..ac10f4b6
--- /dev/null
+++ b/docs/offeredapis/swagger/pms-api.yaml
@@ -0,0 +1,842 @@
+openapi: 3.0.1
+info:
+  title: A1 Policy management service
+  description: 'The O-RAN Non-RT RIC PolicyAgent provides a REST API for management of policices. It provides support for: -Supervision of clients (R-APPs) to eliminate stray policies in case of failure -Consistency monitoring of the SMO view of policies and the actual situation in the RICs -Consistency monitoring of RIC capabilities (policy types) -Policy configuration. This includes: -One REST API towards all RICs in the network -Query functions that can find all policies in a RIC, all policies owned by a service (R-APP), all policies of a type etc. -Maps O1 resources (ManagedElement) as defined in O1 to the controlling RIC
+    of A1 policices.'
+  version: "1.0"
+servers:
+- url: https://localhost:8433/
+- url: http://localhost:8081/
+tags:
+- name: A1 Policy Management
+  description: Policy Controller
+- name: Health check
+  description: Status Controller
+- name: RIC Repository
+  description: Ric Repository Controller
+- name: Service registry and supervision
+  description: Service Controller
+paths:
+  /policies:
+    get:
+      tags:
+      - A1 Policy Management
+      summary: Query policies
+      operationId: getPoliciesUsingGET
+      parameters:
+      - name: ric
+        in: query
+        description: The name of the Near-RT RIC to get policies for.
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'ric1'
+      - name: service
+        in: query
+        description: The name of the service to get policies for.
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'controlpanel'
+      - name: type
+        in: query
+        description: The name of the policy type to get policies for.
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: '1'
+      responses:
+        200:
+          description: Policies
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/PolicyInfo'
+              examples:
+                OSC:
+                  $ref: '#/components/examples/Policies-OSC'
+                STD:
+                  $ref: '#/components/examples/Policies-STD'
+        404:
+          description: RIC or type not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: RIC not found
+      deprecated: false
+  /policy:
+    get:
+      tags:
+      - A1 Policy Management
+      summary: Returns a policy configuration
+      operationId: getPolicyUsingGET
+      parameters:
+      - name: id
+        in: query
+        description: The identity of the policy instance.
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'e26d76e1-b43f-427e-a3c2-b7c4e05a6431'
+      responses:
+        200:
+          description: Policy found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: object
+              examples:
+                OSC:
+                  $ref: '#/components/examples/Policy-OSC'
+                STD:
+                  $ref: '#/components/examples/Policy-STD'
+        404:
+          description: Policy is not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: 'Could not find policy: e26d76e1-b43f-427e-a3c2-b7c4e05a6431'
+      deprecated: false
+    put:
+      tags:
+      - A1 Policy Management
+      summary: Put a policy
+      operationId: putPolicyUsingPUT
+      parameters:
+      - name: id
+        in: query
+        description: The identity of the policy instance.
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: '73428e58-1670-4972-8498-e7e8f1003631'
+      - name: ric
+        in: query
+        description: The name of the Near-RT RIC where the policy will be created.
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'ric1'
+      - name: service
+        in: query
+        description: The name of the service creating the policy.
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'Service1'
+      - name: transient
+        in: query
+        description: If the policy is transient or not (boolean defaulted to false).
+          A policy is transient if it will be forgotten when the service needs to
+          reconnect to the Near-RT RIC.
+        allowEmptyValue: false
+        schema:
+          type: boolean
+          default: false
+        example: false
+      - name: type
+        in: query
+        description: The name of the policy type. The policy type is mandatory for OSC A1 version and should not be provided for STD A1 version.
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'STD_PolicyModelUnconstrained_0.2.0'
+      requestBody:
+        description: jsonBody
+        content:
+          application/json:
+            schema:
+              type: object
+              example:
+                scope:
+                  qosId: "3"
+                  ueId: "1"
+                statement:
+                  priorityLevel: 1
+        required: true
+      responses:
+        200:
+          description: Policy updated
+        201:
+          description: Policy created
+        404:
+          description: RIC or policy type is not found
+        423:
+          description: RIC is not operational
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: 'Ric is not operational, RIC name:ric1, state:UNAVAILABLE'
+    delete:
+      tags:
+      - A1 Policy Management
+      summary: Delete a policy
+      operationId: deletePolicyUsingDELETE
+      parameters:
+      - name: id
+        in: query
+        description: The identity of the policy instance.
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: '73428e58-1670-4972-8498-e7e8f1003631'
+      responses:
+        200:
+          description: OK
+        204:
+          description: Policy deleted
+        404:
+          description: Policy is not found
+        423:
+          description: RIC is not operational
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: 'Ric is not operational, RIC name:ric1,state:UNAVAILABLE'
+      deprecated: false
+  /policy_ids:
+    get:
+      tags:
+      - A1 Policy Management
+      summary: Query policies, only IDs returned
+      operationId: getPolicyIdsUsingGET
+      parameters:
+      - name: ric
+        in: query
+        description: The name of the Near-RT RIC to get policies for.
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'ric1'
+      - name: service
+        in: query
+        description: The name of the service to get policies for.
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'Service1'
+      - name: type
+        in: query
+        description: The name of the policy type to get policies for.
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: '1'
+      responses:
+        200:
+          description: Policy ids
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: array
+                items:
+                  type: string
+              examples:
+                OSC:
+                  value:
+                    - 73428e58-1670-4972-8498-e7e8f1003631
+                    - 73428e58-1670-4972-8498-e7e8f100363e
+                STD:
+                  value:
+                    - 73428e58-1670-4972-8498-e7e8f1003632
+                    - 73428e58-1670-4972-8498-e7e8f1003634
+        404:
+          description: RIC or type not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: RIC not found
+      deprecated: false
+  /policy_schema:
+    get:
+      tags:
+      - A1 Policy Management
+      summary: Returns one policy type schema definition. Applicable only for OSC Version.
+      operationId: getPolicySchemaUsingGET
+      parameters:
+      - name: id
+        in: query
+        description: The identity of the policy type to get the definition for.
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: '11'
+      responses:
+        200:
+          description: Policy schema
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: object
+              examples:
+                OSC:
+                  value:
+                    $schema: http://json-schema.org/draft-07/schema#
+                    description: QoS policy type
+                    title: "1"
+                    type: object
+                    properties:
+                      scope:
+                        additionalProperties: false
+                        type: object
+                        properties:
+                          qosId:
+                            type: string
+                          ueId:
+                            type: string
+                        required:
+                        - ueId
+                        - qosId
+                      statement:
+                        additionalProperties: false
+                        type: object
+                        properties:
+                          priorityLevel:
+                            type: number
+                        required:
+                        - priorityLevel
+        404:
+          description: Type not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: 'org.oransc.policyagent.exceptions.ServiceException: Could
+                  not find type: 11'
+      deprecated: false
+  /policy_schemas:
+    get:
+      tags:
+      - A1 Policy Management
+      summary: Returns policy type schema definitions
+      operationId: getPolicySchemasUsingGET
+      parameters:
+      - name: ric
+        in: query
+        description: The name of the Near-RT RIC to get the definitions for.
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: ric1
+      responses:
+        200:
+          description: Policy schemas
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties: {}
+              examples:
+                OSC:
+                  value:
+                    - $schema: http://json-schema.org/draft-07/schema#
+                      description: QoS policy type
+                      title: "1"
+                      type: object
+                      properties:
+                        scope:
+                          additionalProperties: false
+                          type: object
+                          properties:
+                            qosId:
+                              type: string
+                            ueId:
+                              type: string
+                          required:
+                          - ueId
+                          - qosId
+                        statement:
+                          additionalProperties: false
+                          type: object
+                          properties:
+                            priorityLevel:
+                              type: number
+                          required:
+                          - priorityLevel
+        404:
+          description: RIC is not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: 'org.oransc.policyagent.exceptions.ServiceException: Could
+                  not find ric: ric1'
+      deprecated: false
+  /policy_status:
+    get:
+      tags:
+      - A1 Policy Management
+      summary: Returns a policy status
+      operationId: getPolicyStatusUsingGET
+      parameters:
+      - name: id
+        in: query
+        description: The identity of the policy.
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 73428e58-1670-4972-8498-e7e8f100363q
+      responses:
+        200:
+          description: Policy status
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: object
+              examples:
+                OSC:
+                  value:
+                    instance_status: NOT IN EFFECT
+                    has_been_deleted: "false"
+                    created_at: 07/20/2020, 17:15:39
+                STD:
+                  value:
+                    enforceStatus: UNDEFINED
+        404:
+          description: Policy is not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: 'Could not find policy: 73428e58-1670-4972-8498-e7e8f100363q'
+      deprecated: false
+  /policy_types:
+    get:
+      tags:
+      - A1 Policy Management
+      summary: Query policy type names
+      operationId: getPolicyTypesUsingGET
+      parameters:
+      - name: ric
+        in: query
+        description: The name of the Near-RT RIC to get types for.
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'ric11'
+      responses:
+        200:
+          description: Policy type names
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: array
+                items:
+                  type: string
+              examples:
+                OSC:
+                  value:
+                    - "1"
+        404:
+          description: RIC is not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: 'org.oransc.policyagent.exceptions.ServiceException: Could
+                  not find ric: ric11'
+      deprecated: false
+  /ric:
+    get:
+      tags:
+      - RIC Repository
+      summary: Returns the name of a RIC managing one Mananged Element
+      operationId: getRicUsingGET
+      parameters:
+      - name: managedElementId
+        in: query
+        description: The identity of the Managed Element
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'Node 1'
+      responses:
+        200:
+          description: RIC is found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: ric1
+        404:
+          description: RIC is not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: No RIC found
+      deprecated: false
+  /rics:
+    get:
+      tags:
+      - RIC Repository
+      summary: Query Near-RT RIC information
+      operationId: getRicsUsingGET
+      parameters:
+      - name: policyType
+        in: query
+        description: The name of the policy type
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'STD_PolicyModelUnconstrained_0.2.0'
+      responses:
+        200:
+          description: OK
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/RicInfo'
+        404:
+          description: Policy type is not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: Policy type not found
+      deprecated: false
+  /service:
+    put:
+      tags:
+      - Service registry and supervision
+      summary: Register a service
+      operationId: putServiceUsingPUT
+      requestBody:
+        description: registrationInfo
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ServiceRegistrationInfo'
+        required: true
+      responses:
+        200:
+          description: Service updated
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+              example: OK
+        201:
+          description: Service created
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: OK
+        400:
+          description: The ServiceRegistrationInfo is not accepted
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: Missing mandatory parameter 'serviceName'
+        404:
+          description: Not Found
+      deprecated: false
+      x-codegen-request-body-name: registrationInfo
+  /services:
+    get:
+      tags:
+      - Service registry and supervision
+      summary: Returns service information
+      operationId: getServicesUsingGET
+      parameters:
+      - name: name
+        in: query
+        description: The name of the service
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'service1'
+      responses:
+        200:
+          description: OK
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: array
+                example:
+                - serviceName: "service1"
+                  keepAliveIntervalSeconds: 1000
+                  timeSinceLastActivitySeconds: 7
+                  callbackUrl: http://localhost:8080
+                items:
+                  $ref: '#/components/schemas/ServiceStatus'
+        404:
+          description: Service is not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: Service not found
+      deprecated: false
+    delete:
+      tags:
+      - Service registry and supervision
+      summary: Delete a service
+      operationId: deleteServiceUsingDELETE
+      parameters:
+      - name: name
+        in: query
+        description: The name of the service
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'service1'
+      responses:
+        200:
+          description: OK
+        204:
+          description: OK
+        404:
+          description: Service not found
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: 'Could not find service: service1'
+      deprecated: false
+  /services/keepalive:
+    put:
+      tags:
+      - Service registry and supervision
+      summary: Heartbeat from a serice
+      operationId: keepAliveServiceUsingPUT
+      parameters:
+      - name: name
+        in: query
+        description: The name of the service
+        required: true
+        allowEmptyValue: false
+        schema:
+          type: string
+        example: 'service1'
+      responses:
+        200:
+          description: Service supervision timer refreshed, OK
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: OK
+        201:
+          description: Created
+        404:
+          description: The service is not found, needs re-registration
+          content:
+            text/plain;charset=ISO-8859-1:
+              schema:
+                type: string
+                example: 'Could not find service: service1'
+      deprecated: false
+  /status:
+    get:
+      tags:
+      - Health check
+      summary: Returns status and statistics of this service
+      operationId: getStatusUsingGET
+      responses:
+        200:
+          description: Service is living
+          content:
+            '*/*':
+              schema:
+                type: string
+                example: alive
+        404:
+          description: Not Found
+      deprecated: false
+components:
+  schemas:
+    PolicyInfo:
+      title: PolicyInfo
+      type: object
+      properties:
+        id:
+          type: string
+          description: identity of the policy
+        json:
+          type: object
+          properties: {}
+          description: the configuration of the policy
+        lastModified:
+          type: string
+          description: timestamp, last modification time
+        ric:
+          type: string
+          description: identity of the target Near-RT RIC
+        service:
+          type: string
+          description: the name of the service owning the policy
+        type:
+          type: string
+          description: name of the policy type
+    RicInfo:
+      title: RicInfo
+      type: object
+      properties:
+        managedElementIds:
+          type: array
+          description: O1 identities for managed entities
+          items:
+            type: string
+        policyTypes:
+          type: array
+          description: supported policy types
+          items:
+            type: string
+        ricName:
+          type: string
+          description: identity of the ric
+        state:
+          type: string
+          description: state info
+      example:
+      - ricName: ric1
+        managedElementIds:
+          - ME-1
+          - ME-2
+        policyTypes:
+          - '1'
+        state: AVAILABLE
+      - ricName: ric3
+        managedElementIds:
+          - ME-1
+          - ME-2
+        policyTypes:
+          - ''
+        state: AVAILABLE
+      - ricName: ric2
+        managedElementIds:
+          - ME-1
+          - ME-2
+        policyTypes: []
+        state: AVAILABLE
+      - ricName: ric4
+        managedElementIds:
+          - ME-1
+          - ME-2
+        policyTypes:
+          - ''
+        state: AVAILABLE
+    ServiceRegistrationInfo:
+      title: ServiceRegistrationInfo
+      required:
+      - serviceName
+      type: object
+      properties:
+        callbackUrl:
+          type: string
+          description: callback for notifying of RIC synchronization
+        keepAliveIntervalSeconds:
+          type: integer
+          description: keep alive interval for the service. This is a heartbeat supervision
+            of the service, which in regular intevals must invoke a 'keepAlive' REST
+            call. When a service does not invoke this call within the given time,
+            it is considered unavailble. An unavailable service will be automatically
+            deregistered and its policies will be deleted. Value 0 means no timeout
+            supervision.
+          format: int64
+        serviceName:
+          type: string
+          description: identity of the service
+      example:
+        callbackUrl: http://localhost:9080
+        keepAliveIntervalSeconds: 1000
+        serviceName: service1
+    ServiceStatus:
+      title: ServiceStatus
+      type: object
+      properties:
+        callbackUrl:
+          type: string
+          description: callback for notifying of RIC synchronization
+        keepAliveIntervalSeconds:
+          type: integer
+          description: policy keep alive timeout
+          format: int64
+        serviceName:
+          type: string
+          description: identity of the service
+        timeSinceLastActivitySeconds:
+          type: integer
+          description: time since last invocation by the service
+          format: int64
+  examples:
+    Policies-STD:
+      value:
+        - id: a986eb38-aac3-4897-bdf5-0333ea2bf730
+          type: ''
+          ric: ric3
+          json:
+            scope:
+              ueId: ue1
+              groupId: group1
+              sliceId: slice1
+              qosId: qos1
+              cellId: cell1
+            statement:
+              priorityLevel: 5
+          service: controlpanel
+          lastModified: '2020-07-22T12:21:48.157854Z'
+    Policies-OSC:
+      value:
+        - id: 73428e58-1670-4972-8498-e7e8f1003631
+          type: '1'
+          ric: ric1
+          json:
+            scope:
+              qosId: '36'
+              ueId: '1'
+            statement:
+              priorityLevel: 1
+          service: c
+          lastModified: '2020-07-20T17:16:18.244383Z'
+        - id: 73428e58-1670-4972-8498-e7e8f100363e
+          type: '1'
+          ric: ric1
+          json:
+            scope:
+              qosId: '34'
+              ueId: '1'
+            statement:
+              priorityLevel: 1
+          service: controlpanel
+          lastModified: '2020-07-20T17:15:39.320469Z'
+    Policy-STD:
+      value:
+        scope:
+          ueId: ue1
+          groupId: group1
+          sliceId: slice1
+          qosId: qos1
+          cellId: cell1
+        statement:
+          priorityLevel: 5
+    Policy-OSC:
+      value:
+        scope:
+          qosId: '36'
+          ueId: '1'
+        statement:
+          priorityLevel: 1
\ No newline at end of file