Alignment of the simple edge discovery API as per the CAMARA commonality group guidelines

code/API_definitions/simple_edge_discovery.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.0
+openapi: 3.0.3
 info:
   title: Simple MEC Discovery API
   version: 0.8.1
@@ -14,10 +14,22 @@ info:
   license:
     name: Apache 2.0
     url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+externalDocs:
+  description: Product documentation at CAMARA
+  url: https://github.com/camaraproject/
+
 servers:
   # Added by API Auto Mocking Plugin
-  - description: SwaggerHub API Auto Mocking
-    url: https://virtserver.swaggerhub.com/alphatest/SimpleAPI/1.1.2
+  - url: '{apiRoot}/{basePath}'
+    variables:
+      apiRoot:
+        default: http://localhost:9091
+        description: API root
+      basePath:
+        default: /mecplatforms/v0
+        description: Base path for the get MEC platform API
+security:
+  - oAuth2ClientCredentials: []
 
 tags:
   - name: Discovery
@@ -49,6 +61,11 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         default:
           $ref: '#/components/responses/Unexpected'
+      security:
+        - oAuth2ClientCredentials: []
+        - three_legged:
+          - "mec-platform-read"
+
       tags:
         - Discovery
       operationId: bookmark
@@ -86,6 +103,12 @@ paths:
                         - $ref: '#/components/schemas/LinksCommon'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        "403":
+          $ref: "#/components/responses/Generic403"
+        "500":
+          $ref: "#/components/responses/Generic500"
+        "503":
+          $ref: "#/components/responses/Generic503"
         default:
           $ref: '#/components/responses/Unexpected'
       tags:
@@ -94,6 +117,24 @@ paths:
       description: ON receiving this request, the network will calculate which of its MEC platforms have the shortest network path to the UE (terminal) from which the request was made. 
 
 components:
+  securitySchemes:
+    oAuth2ClientCredentials:
+      description: |
+        The Get MEC Platform API makes use of the OAUTH 2.0 client credentials grant which is applicable for server to server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: "{tokenUrl}"
+          scopes: {}  
+    three_legged:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://auth.example.com/authorize
+          tokenUrl: https://auth.example.com/token
+          scopes:
+            mecplatforms-read: Retrieve list of MEC Platforms
+
   schemas:
     Resources:
       type: array
@@ -183,7 +224,24 @@ components:
         - GPSI
     TypesUEIdentity:
       description: Identifier value for User Equipment. The type of identifier is defined by the 'UEIdentityType' parameter.
-      type: string         
+      type: string
+    ErrorInfo:
+      type: object
+      properties:
+        status:
+          type: integer
+          description: HTTP status code returned along with this error response
+        code:
+          type: string
+          description: Code given to this error
+        message:
+          type: string
+          description: Detailed error description
+      required:
+        - status
+        - code
+        - message
+
 ###########################################
 # LINKS
 ###########################################
@@ -389,4 +447,35 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/TypesError'
+    Generic403:
+      description: Forbidden
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            status: 403
+            code: PERMISSION_DENIED
+            message: "Operation not allowed: ..."
+    Generic500:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            status: 500
+            code: INTERNAL
+            message: "Internal server error: ..."
+    Generic503:
+      description: Service unavailable
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            status: 503
+            code: UNAVAILABLE
+            message: "Service unavailable"
+