From d3bd0d5b48265f5f9e1e872cfdded385a0d28725 Mon Sep 17 00:00:00 2001
From: Stefan Hanreich <s.hanreich@proxmox.com>
Date: Thu, 4 Sep 2025 10:18:33 +0200
Subject: api: vnets: update schema of endpoints

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@proxmox.com>
Reviewed-by: Dominik Csapak <d.csapak@proxmox.com>
Tested-by: Dominik Csapak <d.csapak@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,
         },
     };
 }
-- 
cgit v1.2.3