Clean up OpenAPI specs from CAMARA

catalog/numberverification/numberverification_openapi.yaml

@@ -28,36 +28,35 @@ info:
   version: 0.3.1
   termsOfService: http://example.com/terms/
   contact:
-    name: API Support
-    url: http://www.example.com/support
-    email: support@example.com
+    name: Telefónica Open Gateway DevRel
+    url: https://opengateway.telefonica.com/en/developer-hub
+    email: devrel@telefonica.com
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
 servers:
-  - url: https://{host}{basePath}
+  - url: "{host}/number-verification/{version}"
     variables:
       host:
-        default: api.example.com
-        description: Host that serves the API
-      basePath:
-        default: /number-verification/v0
-        description: Base path for the number verification API
-tags:
-  - name: Phone number verify
-    description: API operation to verify a phone number received as input. It can be received either in plain text or hashed format.
-  - name: Phone number share
-    description: API operation to return the phone number associated to the access token.
+        default: sandbox.opengateway.telefonica.com/apigateway
+        description: gateway URL
+      version:
+        default: v0
+        description: Version of the Number Verification API
 paths:
   /verify:
     post:
-      tags:
-        - Phone number verify
-      summary: Verifies if the received hashed/plain text phone number matches the phone number associated with the access token
+      summary: /verify
+      tags: 
+        -  Verify a phone number
       description: |
-        Verifies if the specified phone number (plain text or hashed format) matches the one that the user is currently using.
+        Verifies if the specified phone number (plain text or hashed format) matches the one associated with the access token.
          - The number verification will be done for the user that has authenticated via mobile network and so their `sub` is in the access token
          - It returns true/false depending on if the hashed phone number received as input matches the authenticated user's `device phone number` associated to the access token
+
+        Check the [Authorization guide](/docs/authorization) on how to get an OAuth2 token, with the following purpose:
+
+        `dpv:FraudPreventionAndDetection#number-verification-verify-read`
       operationId: phoneNumberVerify
       parameters:
         - in: header
@@ -99,55 +98,17 @@ paths:
       security:
         - three_legged:
           - number-verification-verify-read
-  /device-phone-number:
-    get:
-      tags:
-        - Phone number share
-      summary: Returns the phone number associated with the access token
-      description: |
-        Returns the phone number so the API clients can verify the number themselves:
-         - It will be done for the user that has authenticated via mobile network and so their `sub` is in the access token
-         - It returns the authenticated user's `device phone number` associated to the access token
-      operationId: phoneNumberShare
-      parameters:
-        - in: header
-          name: x-correlator
-          required: false
-          description: Correlation id for the different services
-          schema:
-            type: string
-      responses:
-        '200':
-          description: OK
-          headers:
-            x-correlator:
-              description: Correlation id for the different services
-              schema:
-                type: string
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/NumberVerificationShareResponse'
-        '400':
-          $ref: '#/components/responses/Generic400'
-        '401':
-          $ref: '#/components/responses/Generic401'
-        '403':
-          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
-        '500':
-          $ref: '#/components/responses/Generic500'
-        '503':
-          $ref: '#/components/responses/Generic503'
-        '504':
-          $ref: '#/components/responses/Generic504'
-      security:
-        - three_legged:
-          - number-verification-share-read
 components:
   securitySchemes:
     three_legged:
-      type: openIdConnect
-      openIdConnectUrl: https://example.com/.well-known/openid-configuration
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://{host}/authorize
+          tokenUrl: https://{host}/token
+          scopes:
+            number-verification-verify-read: phoneNumberVerify operation
+            number-verification-share-read: phoneNumberShare operation
   schemas:
     NumberVerificationRequestBody:
       type: object

catalog/simswap/simswap_openapi.yaml

@@ -14,7 +14,9 @@ info:
 
   termsOfService: http://swagger.io/terms/
   contact:
-    email: [email protected]
+    name: Telefónica Open Gateway DevRel
+    url: https://opengateway.telefonica.com/en/developer-hub
+    email: [email protected]
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -23,39 +25,45 @@ externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/
 servers:
-  - url: "{apiRoot}/{basePath}"
+  - url: "{host}/sim-swap/{version}"
     variables:
-      apiRoot:
-        default: http://localhost:9091
-        description: API root
-      basePath:
-        default: sim-swap/v0
-        description: Base path for the simSwap API
+      host:
+        default: sandbox.opengateway.telefonica.com/apigateway
+        description: API gateway URL
+      version:
+        default: v0
+        description: Version of the SIM Swap API
 paths:
-  /retrieve-date:
+  /check:
     post:
+      summary: /check
+      tags: 
+        -  Check for a SIM swap
       security:
         - three_legged:
-          - retrieve-sim-swap-date  
-      tags:
-        - Retrieve SIM swap date
-      description: Get timestamp of last MSISDN <-> IMSI pairing change for a mobile user account provided with MSIDN.
-      operationId: retrieveSimSwapDate
+          - check-sim-swap
+      description: |
+        Check if SIM swap has been performed during a past period
+
+        Check the [Authorization guide](/docs/authorization) on how to get an OAuth2 token, with the following purpose:
+
+        `dpv:FraudPreventionAndDetection#sim-swap`
+      operationId: checkSimSwap
       requestBody:
         description: |
-          Create a SIM swap date request for a MSISDN identifier.
+          Create a check SIM swap request for a MSISDN identifier.
         content :
           application/json:
             schema:
-              $ref: "#/components/schemas/CreateSimSwapDate"
+              $ref: "#/components/schemas/CreateCheckSimSwap"
         required: true
       responses:
         "200":
-          description: Contains information about SIM swap change
+          description: Returns whether a SIM swap has been performed during a past period
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SimSwapInfo"
+                $ref: "#/components/schemas/CheckSimSwapInfo"
         "400":
           $ref: "#/components/responses/Generic400"
         "401":
@@ -72,30 +80,36 @@ paths:
           $ref: "#/components/responses/Generic503"
         "504":
           $ref: "#/components/responses/Generic504"
-  /check:
+  /retrieve-date:
     post:
+      summary: /retrieve-date
+      tags: 
+        -  Retrieve latest SIM swap date
       security:
         - three_legged:
-          - check-sim-swap
-      tags:
-      - Check SIM swap
-      description: Check if SIM swap has been performed during a past period
-      operationId: checkSimSwap
+          - retrieve-sim-swap-date  
+      description: |
+        Get timestamp of last MSISDN <-> IMSI pairing change for a mobile user account provided with MSIDN.
+
+        Check the [Authorization guide](/docs/authorization) on how to get an OAuth2 token, with the following purpose:
+
+        `dpv:FraudPreventionAndDetection#sim-swap`
+      operationId: retrieveSimSwapDate
       requestBody:
         description: |
-          Create a check SIM swap request for a MSISDN identifier.
+          Create a SIM swap date request for a MSISDN identifier.
         content :
           application/json:
             schema:
-              $ref: "#/components/schemas/CreateCheckSimSwap"
+              $ref: "#/components/schemas/CreateSimSwapDate"
         required: true
       responses:
         "200":
-          description: Returns whether a SIM swap has been performed during a past period
+          description: Contains information about SIM swap change
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/CheckSimSwapInfo"
+                $ref: "#/components/schemas/SimSwapInfo"
         "400":
           $ref: "#/components/responses/Generic400"
         "401":
@@ -118,8 +132,8 @@ components:
       type: oauth2
       flows:
         authorizationCode:
-          authorizationUrl: https://auth.example.com/authorize
-          tokenUrl: https://auth.example.com/token
+          authorizationUrl: https://{host}/authorize
+          tokenUrl: https://{host}/token
           scopes:
             check-sim-swap: checkSimSwap operation
             retrieve-sim-swap-date: retrieveSimSwapDate operation