updated specs for byoip (#1216)

* updated specs for byoip

* review comments

Author: rbhatia-code

specification/resources/load_balancers/loadBalancers_update.yml

@@ -22,7 +22,7 @@ requestBody:
   content:
     application/json:
       schema:
-        $ref: 'models/load_balancer_create.yml'
+        $ref: 'models/load_balancer_update.yml'
 
       examples:
         load_balancer_update_request:

specification/resources/load_balancers/models/attributes.yml

@@ -15,3 +15,16 @@ load_balancer_droplet_tag:
     example: prod:web
     description: The name of a Droplet tag corresponding to Droplets assigned
       to the load balancer.
+
+load_balancer_ip:
+  ip:
+    type: string
+    pattern: '^$|^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$'
+    example: '203.0.113.42'
+    description: >-
+      An optional IP address to assign to the load balancer from one of your
+      Bring Your Own IP (BYOIP) prefixes. The address must be an unassigned
+      BYOIP address on your account in the same region as the load balancer.
+      If omitted, DigitalOcean assigns a public IP address automatically. This
+      field is only applied when creating the load balancer, cannot be changed
+      afterward, and is not supported for `GLOBAL` or `INTERNAL` load balancers.

specification/resources/load_balancers/models/load_balancer.yml

@@ -1,6 +1,16 @@
 allOf:
 - $ref: 'load_balancer_base.yml'
 
+- type: object
+  properties:
+    ip:
+      type: string
+      pattern: '^$|^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$'
+      readOnly: true
+      example: '104.131.186.241'
+      description: An attribute containing the public-facing IP address of the
+        load balancer.
+
 - type: object
   properties:
     region:

specification/resources/load_balancers/models/load_balancer_base.yml

@@ -22,14 +22,6 @@ properties:
       default project. If an invalid project ID is provided, the load balancer will 
       not be created.
 
-  ip:
-    type: string
-    pattern: '^$|^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$'
-    readOnly: true
-    example: '104.131.186.241'
-    description: An attribute containing the public-facing IP address of the
-      load balancer.
-  
   ipv6:
     type: string
     readOnly: true

specification/resources/load_balancers/models/load_balancer_create.yml

@@ -1,34 +1,11 @@
-oneOf:
-  - title: Assign Droplets by ID
-    allOf:
-    - type: object
-      properties:
-        $ref: 'attributes.yml#/load_balancer_droplet_ids'
+description: >-
+  The request schema for creating a load balancer. This is the same as the
+  update schema with the addition of the create-only `ip` field, which assigns
+  a Bring Your Own IP (BYOIP) address to the load balancer.
 
-    - type: object
-      properties:
-        region:
-          $ref: '../../../shared/attributes/region_slug.yml'
+allOf:
+  - $ref: 'load_balancer_update.yml'
 
-    - $ref: 'load_balancer_base.yml'
-
-    required:
-    - droplet_ids
-    - region
-
-  - title: Assign Droplets by Tag
-    allOf:
-    - type: object
-      properties:
-        $ref: 'attributes.yml#/load_balancer_droplet_tag'
-
-    - type: object
-      properties:
-        region:
-          $ref: '../../../shared/attributes/region_slug.yml'
-
-    - $ref: 'load_balancer_base.yml'
-
-    required:
-    - tag
-    - region
+  - type: object
+    properties:
+      $ref: 'attributes.yml#/load_balancer_ip'

specification/resources/load_balancers/models/load_balancer_update.yml

@@ -0,0 +1,34 @@
+oneOf:
+  - title: Assign Droplets by ID
+    allOf:
+    - type: object
+      properties:
+        $ref: 'attributes.yml#/load_balancer_droplet_ids'
+
+    - type: object
+      properties:
+        region:
+          $ref: '../../../shared/attributes/region_slug.yml'
+
+    - $ref: 'load_balancer_base.yml'
+
+    required:
+    - droplet_ids
+    - region
+
+  - title: Assign Droplets by Tag
+    allOf:
+    - type: object
+      properties:
+        $ref: 'attributes.yml#/load_balancer_droplet_tag'
+
+    - type: object
+      properties:
+        region:
+          $ref: '../../../shared/attributes/region_slug.yml'
+
+    - $ref: 'load_balancer_base.yml'
+
+    required:
+    - tag
+    - region

specification/resources/vpc_nat_gateways/models/vpc_nat_gateway_create.yml

@@ -71,6 +71,46 @@ properties:
     example: 30
     description: The TCP timeout in seconds for the VPC NAT gateway.
 
+  egresses:
+    type: object
+    description: >-
+      An optional object specifying the public egress IP address to assign to
+      the VPC NAT gateway. Provide this only to use a specific address. If
+      omitted, DigitalOcean allocates a public IP address automatically.
+    properties:
+      public_gateways:
+        type: array
+        description: >-
+          An array containing a single public gateway object that sets the
+          gateway's public egress IP address.
+        items:
+          type: object
+          description: >-
+            Specify the address using either `ip` or `ipv4`. Both fields accept
+            the same value and `ip` takes precedence if both are provided. The
+            assigned address is returned in the `ipv4` field of GET and list
+            responses.
+          properties:
+            ip:
+              type: string
+              example: 203.0.113.42
+              description: >-
+                The public egress IP address to assign to the VPC NAT gateway,
+                and the preferred field for setting it. Provide an unassigned
+                Bring Your Own IP (BYOIP) address on your account in the same
+                region to use your own IP address. This field is only applied
+                when creating the gateway and cannot be changed afterward. The
+                assigned address is returned as `ipv4` in GET and list
+                responses.
+            ipv4:
+              type: string
+              example: 203.0.113.42
+              description: >-
+                An alternative to `ip` for setting the public egress IP address
+                on create. Accepts the same value as `ip`, which takes
+                precedence if both are provided. This field is only applied when
+                creating the gateway and cannot be changed afterward.
+
 required:
   - name
   - type

specification/resources/vpc_nat_gateways/models/vpc_nat_gateway_get.yml

@@ -83,7 +83,10 @@ properties:
             ipv4:
               type: string
               example: 174.138.113.197
-              description: IPv4 address of the public gateway.
+              description: >-
+                The public egress IPv4 address of the VPC NAT gateway. This is
+                the address assigned to the gateway, which you can optionally
+                set when creating the gateway using the `ip` or `ipv4` field.
     description: An object containing egress information for the VPC NAT gateway.
 
   udp_timeout_seconds: