Improve docstrings, try to localize suppressions

Azure · Feb 13, 2024 · 87cd804 · 87cd804
1 parent e00bba5
commit 87cd804
Show file tree

Hide file tree

Showing 10 changed files with 39 additions and 63 deletions.
diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/common.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/common.tsp
@@ -36,12 +36,10 @@ model NetworkIdentifier {
   @doc("The type of identifier for the network. one of: 'IPv4', 'IPv6', 'NetworkCode'")
   identifierType: string;
 
-  /**
-  The network identifier in a format matching the type above:
-  - IPv4 of a device in dotted-quad form 1.2.3.4.
-  - IPv6 of a device in IETF 5952 format.
-  - NetworkCode matching our documentation or an output from /Network:retrieve."
-  */
+  @doc("""
+    The network identifier, based on the identifierType: an IPv4 address, and IPv6 address, or a Network Code.
+    A Network Code may be obtained from APC documentation or from the APC /Network:retrieve endpoint.
+    """)
   identifier: string;
 }
 
@@ -91,10 +89,7 @@ model Ipv6AddressModel {
 
 @doc("IPv4 device indicator")
 model Ipv4Address {
-  /** IPv4 address may be specified in form <address/mask> as:
-          - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.
-          - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.
-            In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version. */
+  @doc("An IPv4 address. This may be specified as an exact address, or as a subnet in CIDR notation.")
   ipv4: string;
 
   @doc("User equipment port.")
@@ -103,13 +98,7 @@ model Ipv4Address {
 
 @doc("IPv6 device indicator")
 model Ipv6Address {
-  /** IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as:
-          - address - The /128 subnet is optional for single addresses:
-            - 2001:db8:85a3:8d3:1319:8a2e:370:7344
-            - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
-          - address/mask - an IP v6 number with a mask:
-            - 2001:db8:85a3:8d3::0/64
-            - 2001:db8:85a3:8d3::/64 */
+  @doc("An IPv6 address. This may be specified as an exact address, or as a subnet in CIDR notation.")
   ipv6: string;
 
   @doc("User equipment port.")

diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/location.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/location.tsp
@@ -51,8 +51,8 @@ model DeviceLocationVerificationContent {
   @maxValue(100)
   accuracy: int32;
 
-  @doc("The device to find the location for.")
-  locationDevice: LocationDevice;
+  @doc("The device to find the location for. Exactly one of Network Access Code, Phone Number, IPv4 address, or IPv6 address")
+  device: LocationDevice;
 }
 
 /// Response models
@@ -64,6 +64,10 @@ model DeviceLocationVerificationResult {
 }
 
 /// Common models
+
+// LocationDevice represents a Device as required by the Location API. The APC team aims
+// to drive commonisation of the underlying CAMARA APIs so that all APIs can share a common Device
+// model in future.
 @doc("Device information needed by operator to provide location information. Include exactly one of these properties to identify your device.")
 model LocationDevice {
   ...NetworkAccessIdentifierModel;

diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/number.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/number.tsp
@@ -13,26 +13,24 @@ namespace Azure.ProgrammableConnectivity;
 @doc("""
   Number operations include Frontend Authentication.
 
-  Users must first make a call to triggerFrontendAuthentication, which redirects the device
-  to the device's Network to authenticate directly. The Network responds with a token.
+  Users first make a call to the endpoint /Number:verify, which returns a redirect to the device's 
+  Network. This is followed by the device to authenticate directly with the Network. The Network 
+  responds with a token and a redirect. This token can be exchanged with APC for a code.
   
-  This redirects the device to APC, where the token is used to verify / retrieve
-  the device number. The second response is a 200 containing the result of the query.
+  Users make a second call to the endpoint /Number:verify including the code. The code is used 
+  to verify the device number. The second response is a 200 containing the result of the query.
 
-  This flow requires some manual interaction from the developer between receiving the 302 redirect,
-  and making a second call to obtain the number verification result. This has therefore been
-  split into two operations, one for the redirect, and one for the result.
+  For more information on the steps required to use Number Verificaiton, see the APC documentation.
 """)
 interface NumberVerification {
+  #suppress "@azure-tools/typespec-azure-core/no-response-body" "302 redirect has no response body"
   @doc("Verifies the phone number (MSISDN) associated with a device. As part of the frontend authorization flow, the device is redirected to the operator network to authenticate directly.")
   @sharedRoute
   @action("verify")
   verifyWithoutCode is Operations.ResourceAction<
     NumberVerificationEndpoint,
     NumberVerificationWithoutCodeContent,
-    // Typespec requires that non-204 responses have a non-empty body. This requirement cannot be suppressed.
-    // Return a model containing only one optional field to get around this.
-    TypeSpec.Http.Response<302> & EmptyResult,
+    TypeSpec.Http.Response<302> & {},
     TraitOverride<ResponseHeadersTrait<{
       @header location: string;
     } & RequestIdResponseHeader>>
@@ -82,19 +80,17 @@ model NumberVerificationWithCodeContent {
 
 /// Response models
 
-@doc("Empty model to return as part of 302 redirect")
-model EmptyResult {
-  @doc("Optional content")
-  content?: string;
-}
-
 @doc("Response verifying number of device")
 model NumberVerificationResult {
   @doc("True if number if the phone number matches the device, False otherwise")
   verificationResult: boolean;
 }
 
 /// Common models
+
+// NumberDevice represents a Device as required by the Number Verification API. The APC team aims
+// to drive commonisation of the underlying CAMARA APIs so that all APIs can share a common Device
+// model in future.
 @doc("Device information to verify phone number. Include exactly one form of phone number.")
 model NumberDevice {
   ...PhoneNumberModel;

diff --git a/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/simswap.tsp b/specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/simswap.tsp
@@ -76,6 +76,9 @@ model SimSwapVerificationResult {
 
 /// Common models
 
+// SimSwapDevice represents a Device as required by the Sim Swap API. The APC team aims
+// to drive commonisation of the underlying CAMARA APIs so that all APIs can share a common Device
+// model in future.
 @doc("Device information needed by operator to find sim swap information.")
 model SimSwapDevice {
   ...PhoneNumberModel;

diff --git a/...ammableConnectivity/examples/2024-02-09-preview/DeviceLocation_Verify_MaximumSet_Gen.json b/...ammableConnectivity/examples/2024-02-09-preview/DeviceLocation_Verify_MaximumSet_Gen.json
@@ -14,7 +14,7 @@
       "latitude": 70,
       "longitude": -161,
       "accuracy": 91,
-      "locationDevice": {
+      "device": {
         "networkAccessIdentifier": "[email protected]",
         "phoneNumber": "+447000000000",
         "ipv4Address": {

diff --git a/...vity/examples/2024-02-09-preview/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json b/...vity/examples/2024-02-09-preview/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json
@@ -15,8 +15,6 @@
     }
   },
   "responses": {
-    "302": {
-      "body": {}
-    }
+    "302": {}
   }
 }
diff --git a/...onnectivity/preview/2024-02-09-preview/examples/DeviceLocation_Verify_MaximumSet_Gen.json b/...onnectivity/preview/2024-02-09-preview/examples/DeviceLocation_Verify_MaximumSet_Gen.json
@@ -14,7 +14,7 @@
       "latitude": 70,
       "longitude": -161,
       "accuracy": 91,
-      "locationDevice": {
+      "device": {
         "networkAccessIdentifier": "[email protected]",
         "phoneNumber": "+447000000000",
         "ipv4Address": {

diff --git a/...view/2024-02-09-preview/examples/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json b/...view/2024-02-09-preview/examples/NumberVerification_VerifyWithoutCode_MaximumSet_Gen.json
@@ -15,8 +15,6 @@
     }
   },
   "responses": {
-    "302": {
-      "body": {}
-    }
+    "302": {}
   }
 }
diff --git a/...ctivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json b/...ctivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json
@@ -201,9 +201,6 @@
         "responses": {
           "302": {
             "description": "Redirection",
-            "schema": {
-              "$ref": "#/definitions/EmptyResult"
-            },
             "headers": {
               "location": {
                 "type": "string"
@@ -610,17 +607,17 @@
           "minimum": 2,
           "maximum": 100
         },
-        "locationDevice": {
+        "device": {
           "$ref": "#/definitions/LocationDevice",
-          "description": "The device to find the location for."
+          "description": "The device to find the location for. Exactly one of Network Access Code, Phone Number, IPv4 address, or IPv6 address"
         }
       },
       "required": [
         "networkIdentifier",
         "latitude",
         "longitude",
         "accuracy",
-        "locationDevice"
+        "device"
       ]
     },
     "DeviceLocationVerificationResult": {
@@ -656,23 +653,13 @@
         "network"
       ]
     },
-    "EmptyResult": {
-      "type": "object",
-      "description": "Empty model to return as part of 302 redirect",
-      "properties": {
-        "content": {
-          "type": "string",
-          "description": "Optional content"
-        }
-      }
-    },
     "Ipv4Address": {
       "type": "object",
       "description": "IPv4 device indicator",
       "properties": {
         "ipv4": {
           "type": "string",
-          "description": "IPv4 address may be specified in form <address/mask> as:\n          - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.\n          - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.\n            In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version."
+          "description": "An IPv4 address. This may be specified as an exact address, or as a subnet in CIDR notation."
         },
         "port": {
           "type": "integer",
@@ -701,7 +688,7 @@
       "properties": {
         "ipv6": {
           "type": "string",
-          "description": "IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as:\n          - address - The /128 subnet is optional for single addresses:\n            - 2001:db8:85a3:8d3:1319:8a2e:370:7344\n            - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128\n          - address/mask - an IP v6 number with a mask:\n            - 2001:db8:85a3:8d3::0/64\n            - 2001:db8:85a3:8d3::/64"
+          "description": "An IPv6 address. This may be specified as an exact address, or as a subnet in CIDR notation."
         },
         "port": {
           "type": "integer",
@@ -767,7 +754,7 @@
         },
         "identifier": {
           "type": "string",
-          "description": "The network identifier in a format matching the type above:\n  - IPv4 of a device in dotted-quad form 1.2.3.4.\n  - IPv6 of a device in IETF 5952 format.\n  - NetworkCode matching our documentation or an output from /Network:retrieve.\""
+          "description": "The network identifier, based on the identifierType: an IPv4 address, and IPv6 address, or a Network Code.\nA Network Code may be obtained from APC documentation or from the APC /Network:retrieve endpoint."
         }
       },
       "required": [

diff --git a/specification/programmableconnectivity/data-plane/readme.md b/specification/programmableconnectivity/data-plane/readme.md
@@ -39,7 +39,8 @@ input-file:
   - Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json
 suppressions:
   - code: ValidResponseCodeRequired
-    reason: APC must return a 302 as part of a non-standard 
+    reason: APC must return a 302 as part of a non-standard frontend authentication flow
+    where: $.paths./number-verification/number:verify.post.responses
 ```
 
 # Code Generation