[pdm-devel] [PATCH pve-network v2 5/6] api: vnets: update schema of endpoints

[Stefan Hanreich]

The possible properties returned by the vnet endpoints were only
partly documented. Add all missing properties and improve descriptions
for existing properties.

Extract all duplicate properties into a separate variable, so we
don't have to rewrite the whole API definition for every endpoint.

Signed-off-by: Stefan Hanreich <s.hanreich at proxmox.com>
---
 src/PVE/API2/Network/SDN/Vnets.pm | 92 ++++++++++++++++++++++++++++++-
 src/PVE/Network/SDN/VnetPlugin.pm | 21 +++++--
 2 files changed, 105 insertions(+), 8 deletions(-)

diff --git a/src/PVE/API2/Network/SDN/Vnets.pm b/src/PVE/API2/Network/SDN/Vnets.pm
index e6eb5d4..1d9e500 100644
--- a/src/PVE/API2/Network/SDN/Vnets.pm
+++ b/src/PVE/API2/Network/SDN/Vnets.pm
@@ -74,6 +74,40 @@ my $check_vnet_access = sub {
     $rpcenv->check_any($authuser, "/sdn/zones/$zoneid/$vnet", $privs);
 };
 
+my $VNET_PROPERTIES = {
+    alias => {
+        type => 'string',
+        description => "Alias name of the VNet.",
+        pattern => qr/[\(\)-_.\w\d\s]{0,256}/i,
+        maxLength => 256,
+        optional => 1,
+    },
+    'isolate-ports' => {
+        type => 'boolean',
+        description =>
+            "If true, sets the isolated property for all interfaces on the bridge of this VNet.",
+        optional => 1,
+    },
+    tag => {
+        type => 'integer',
+        description =>
+            'VLAN Tag (for VLAN or QinQ zones) or VXLAN VNI (for VXLAN or EVPN zones).',
+        optional => 1,
+        minimum => 1,
+        maximum => 16777215,
+    },
+    vlanaware => {
+        type => 'boolean',
+        description => 'Allow VLANs to pass through this VNet.',
+        optional => 1,
+    },
+    zone => {
+        type => 'string',
+        description => 'Name of the zone this VNet belongs to.',
+        optional => 1,
+    },
+};
+
 __PACKAGE__->register_method({
     name => 'index',
     path => '',
@@ -103,7 +137,33 @@ __PACKAGE__->register_method({
         type => 'array',
         items => {
             type => "object",
-            properties => {},
+            properties => {
+                digest => {
+                    type => 'string',
+                    optional => 1,
+                    description => 'Digest of the VNet section.',
+                },
+                state => get_standard_option('pve-sdn-config-state'),
+                type => {
+                    type => 'string',
+                    enum => ['vnet'],
+                    optional => 0,
+                    description => 'Type of the VNet.',
+                },
+                vnet => {
+                    type => 'string',
+                    optional => 0,
+                    description => 'Name of the VNet.',
+                },
+                pending => {
+                    type => 'object',
+                    description =>
+                        'Changes that have not yet been applied to the running configuration.',
+                    optional => 1,
+                    properties => $VNET_PROPERTIES,
+                },
+                %$VNET_PROPERTIES,
+            },
         },
         links => [{ rel => 'child', href => "{vnet}" }],
     },
@@ -171,7 +231,35 @@ __PACKAGE__->register_method({
             },
         },
     },
-    returns => { type => 'object' },
+    returns => {
+        properties => {
+            digest => {
+                type => 'string',
+                optional => 1,
+                description => 'Digest of the VNet section.',
+            },
+            state => get_standard_option('pve-sdn-config-state'),
+            type => {
+                type => 'string',
+                enum => ['vnet'],
+                optional => 0,
+                description => 'Type of the VNet.',
+            },
+            vnet => {
+                type => 'string',
+                optional => 0,
+                description => 'Name of the VNet.',
+            },
+            pending => {
+                type => 'object',
+                description =>
+                    'Changes that have not yet been applied to the running configuration.',
+                optional => 1,
+                properties => $VNET_PROPERTIES,
+            },
+            %$VNET_PROPERTIES,
+        },
+    },
     code => sub {
         my ($param) = @_;
 
diff --git a/src/PVE/Network/SDN/VnetPlugin.pm b/src/PVE/Network/SDN/VnetPlugin.pm
index 035aaca..717438c 100644
--- a/src/PVE/Network/SDN/VnetPlugin.pm
+++ b/src/PVE/Network/SDN/VnetPlugin.pm
@@ -60,30 +60,39 @@ sub properties {
     return {
         zone => {
             type => 'string',
-            description => "zone id",
+            description => 'Name of the zone this VNet belongs to.',
         },
         type => {
-            description => "Type",
+            type => 'string',
+            enum => ['vnet'],
+            description => 'Type of the VNet.',
             optional => 1,
         },
         tag => {
             type => 'integer',
-            description => "vlan or vxlan id",
+            description =>
+                'VLAN Tag (for VLAN or QinQ zones) or VXLAN VNI (for VXLAN or EVPN zones).',
+            optional => 1,
+            minimum => 1,
+            maximum => 16777215,
         },
         vlanaware => {
             type => 'boolean',
-            description => 'Allow vm VLANs to pass through this vnet.',
+            description => 'Allow VLANs to pass through this vnet.',
+            optional => 1,
         },
         alias => {
             type => 'string',
-            description => "alias name of the vnet",
+            description => "Alias name of the VNet.",
             pattern => qr/[\(\)-_.\w\d\s]{0,256}/i,
             maxLength => 256,
             optional => 1,
         },
         'isolate-ports' => {
             type => 'boolean',
-            description => "If true, sets the isolated property for all members of this VNet",
+            description =>
+                "If true, sets the isolated property for all interfaces on the bridge of this VNet.",
+            optional => 1,
         },
     };
 }
-- 
2.47.2