Add OpenAPI v3 specification of onboarder API

Adjust some endpoint PyDoc entries for readability

Signed-off-by: Lott, Christopher (cl778h) <cl778h@att.com>
Change-Id: Idb67d8401e2c1f1631860631cd26cee470c881f4

diff --git a/xapp_onboarder/xapp_onboarder/api/endpoints/charts_ep.py b/xapp_onboarder/xapp_onboarder/api/endpoints/charts_ep.py
index dc2c994..16fbec7 100644 (file)
--- a/xapp_onboarder/xapp_onboarder/api/endpoints/charts_ep.py
+++ b/xapp_onboarder/xapp_onboarder/api/endpoints/charts_ep.py
@@ -32,7 +32,7 @@ class ChartsList(Resource):
     @api.response(500, 'Get helm chart list failed', error_message_model)
     def get(self):
         """
-        Returns the list of charts that have been onboarded.
+        Returns the list of xApp helm charts that have been onboarded.
         """
 
         return get_charts_list()
@@ -41,11 +41,11 @@ class ChartsList(Resource):
 @ns.route('/xapp/<string:xapp_chart_name>')
 class VersionList(Resource):
 
-    @api.response(200, 'Get helm chart list OK')
-    @api.response(500, 'Get helm chart list failed', error_message_model)
+    @api.response(200, 'Get helm chart OK')
+    @api.response(500, 'Get helm chart failed', error_message_model)
     def get(self, xapp_chart_name):
         """
-        Returns the list of charts that have been onboarded.
+        Returns the helm chart for the specified xApp.
         """
         return get_charts_list(xapp_chart_name=xapp_chart_name)
 
@@ -58,7 +58,7 @@ class ChartsFetcher(Resource):
     @api.produces(['application/gzip'])
     def get(self, xapp_chart_name, version):
         """
-        Returns the helm charts that have been onboarded.
+        Returns the helm chart for the specified xApp and version.
         """
 
         content, status = download_chart_package(xapp_chart_name=xapp_chart_name, version=version)
@@ -81,7 +81,7 @@ class ValuesYamlFetcher(Resource):
     @api.produces(['text/x-yaml'])
     def get(self, xapp_chart_name, version):
         """
-        Returns the values.yaml file of the xApp
+        Returns the helm values.yaml file of the specified xApp and version.
         """
 
         content, status = download_values_yaml(xapp_chart_name=xapp_chart_name, version=version)

diff --git a/xapp_onboarder/xapp_onboarder/api/endpoints/health_check_ep.py b/xapp_onboarder/xapp_onboarder/api/endpoints/health_check_ep.py
index d076667..23e8b5c 100644 (file)
--- a/xapp_onboarder/xapp_onboarder/api/endpoints/health_check_ep.py
+++ b/xapp_onboarder/xapp_onboarder/api/endpoints/health_check_ep.py
@@ -41,4 +41,3 @@ class HealthCheck(Resource):
                                          status = "Service not ready.")
             return response_message.get_return()
         return response(model = status_message_model, status_code = 200, status= "OK").get_return()
-

diff --git a/xapp_onboarder/xapp_onboarder/api/endpoints/onboard_ep.py b/xapp_onboarder/xapp_onboarder/api/endpoints/onboard_ep.py
index 222307d..6806bbf 100644 (file)
--- a/xapp_onboarder/xapp_onboarder/api/endpoints/onboard_ep.py
+++ b/xapp_onboarder/xapp_onboarder/api/endpoints/onboard_ep.py
@@ -45,7 +45,7 @@ class OnboardxApps(Resource):
     @api.expect(request_models.xapp_descriptor_post, validate=True)
     def post(self):
         """
-        Onboard xApp with the xApp descriptor and its scehma included in the Json body
+        Onboard xApp using the xApp descriptor and schema in the request body.
         """
         config_file = request.json.get('config-file.json')
         controls_schema_file = request.json.get('controls-schema.json')
@@ -62,10 +62,9 @@ class OnboardxAppsDownload(Resource):
     @api.expect(request_models.xapp_descriptor_download_post, validate=True)
     def post(self):
         """
-        Onboard xApp with xApp descriptor and schema downloading URLs
+        Onboard xApp after downloading the xApp descriptor and schema from the URLs.
         """
         config_file_url = request.json.get('config-file.json_url')
         controls_schema_url = request.json.get('controls-schema.json_url')
 
         return download_config_and_schema_and_onboard(config_file_url, controls_schema_url)
-

diff --git a/xapp_onboarder/xapp_onboarder/xapp-onboarder-api.yaml b/xapp_onboarder/xapp_onboarder/xapp-onboarder-api.yaml
new file mode 100644 (file)
index 0000000..2774976
--- /dev/null
+++ b/xapp_onboarder/xapp_onboarder/xapp-onboarder-api.yaml
@@ -0,0 +1,282 @@
+# ==================================================================================
+#       Copyright (c) 2020 AT&T Intellectual Property.
+#
+#   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.
+# ==================================================================================
+openapi: 3.0.1
+info:
+  title: RIC xApp onboarder API
+  description: APIs to manage the xApp helm charts
+  version: "1.0"
+servers:
+- url: /api/v1
+tags:
+- name: onboard
+  description: onboard xApps
+- name: health
+  description: health check
+- name: charts
+  description: Managing helm charts
+paths:
+  /charts:
+    get:
+      tags:
+      - charts
+      summary: Returns the list of xApp helm charts that have been onboarded
+      operationId: get_charts_list
+      responses:
+        200:
+          description: Get helm chart list OK
+          content: {}
+        500:
+          description: Get helm chart list failed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_message'
+
+  /charts/xapp/{xapp_chart_name}:
+    get:
+      tags:
+      - charts
+      summary: Returns the helm chart for the specified xApp
+      operationId: get_version_list
+      parameters:
+      - name: xapp_chart_name
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        200:
+          description: Get helm chart OK
+          content: {}
+        500:
+          description: Get helm chart failed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_message'
+
+  /charts/xapp/{xapp_chart_name}/ver/{version}:
+    get:
+      tags:
+      - charts
+      summary: Returns the helm chart for the specified xApp and version
+      operationId: get_charts_fetcher
+      parameters:
+      - name: xapp_chart_name
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: version
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        200:
+          description: Get helm chart package OK
+          content: {}
+        500:
+          description: Get helm chart package failed
+          content:
+            application/gzip:
+              schema:
+                $ref: '#/components/schemas/error_message'
+
+  /charts/xapp/{xapp_chart_name}/ver/{version}/values.yaml:
+    get:
+      tags:
+      - charts
+      summary: Returns the helm values
+      description: yaml file of the specified xApp and version.
+      operationId: get_values_yaml_fetcher
+      parameters:
+      - name: xapp_chart_name
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: version
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        200:
+          description: Get helm chart values.yaml OK
+          content: {}
+        500:
+          description: Get helm chart values.yaml failed
+          content:
+            text/x-yaml:
+              schema:
+                $ref: '#/components/schemas/error_message'
+
+  /health:
+    get:
+      tags:
+      - health
+      summary: Returns the health condition of the xApp onboarder
+      operationId: get_health_check
+      responses:
+        200:
+          description: Health check OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/status'
+        500:
+          description: xApp onboarder is not ready
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_message'
+
+  /onboard:
+    post:
+      tags:
+      - onboard
+      summary: Onboard xApp using the xApp descriptor and schema in the request body
+      operationId: post_onboardx_apps
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/descriptor'
+        required: true
+      responses:
+        201:
+          description: xApp onboard successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/status'
+        400:
+          description: xApp descriptor format error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_message'
+        500:
+          description: xApp onboarder is not ready
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_message'
+      x-codegen-request-body-name: payload
+
+  /onboard/download:
+    post:
+      tags:
+      - onboard
+      summary: Onboard xApp after downloading the xApp descriptor and schema from
+        the URLs
+      operationId: post_onboardx_apps_download
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/descriptor_remote'
+        required: true
+      responses:
+        201:
+          description: xApp onboard successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/status'
+        400:
+          description: xApp descriptor format error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_message'
+        500:
+          description: xApp onboarder is not ready
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_message'
+      x-codegen-request-body-name: payload
+
+components:
+  schemas:
+    descriptor:
+      required:
+      - config-file.json
+      type: object
+      properties:
+        config-file.json:
+          $ref: '#/components/schemas/config'
+        controls-schema.json:
+          type: object
+          properties: {}
+          description: Controls schema file body
+    config:
+      required:
+      - version
+      - xapp_name
+      type: object
+      properties:
+        xapp_name:
+          type: string
+          description: Name of the xApp chart
+        version:
+          pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
+          type: string
+          description: Version of the xApp chart
+    error_message:
+      required:
+      - error_message
+      - error_source
+      - status
+      type: object
+      properties:
+        error_source:
+          type: string
+          description: source of the error
+        error_message:
+          type: string
+          description: source of the error
+        status:
+          type: string
+          description: http response message
+    status:
+      required:
+      - status
+      type: object
+      properties:
+        status:
+          type: string
+          description: status of the service
+    descriptor_remote:
+      required:
+      - config-file.json_url
+      type: object
+      properties:
+        config-file.json_url:
+          type: string
+          description: URL to download the config-file.json file
+        controls-schema.json_url:
+          type: string
+          description: URL to download the controls schema.json file
+  responses:
+    MaskError:
+      description: When any error occurs on mask
+      content: {}
+    ParseError:
+      description: When a mask can't be parsed
+      content: {}