Add allowedValues support for API parameter discovery

api/src/main/java/org/apache/cloudstack/api/Parameter.java

@@ -52,5 +52,6 @@
 
     ApiArgValidator[] validations() default {};
 
+    String[] allowedValues() default {};
     boolean acceptedOnAdminPort() default true;
 }

api/src/main/java/org/apache/cloudstack/api/command/admin/vpc/CreateVPCOfferingCmd.java

@@ -92,10 +92,15 @@ public class CreateVPCOfferingCmd extends BaseAsyncCreateCmd {
     @Parameter(name = ApiConstants.SERVICE_CAPABILITY_LIST, type = CommandType.MAP, description = "Desired service capabilities as part of VPC offering", since = "4.4")
     private Map<String, List<String>> serviceCapabilityList;
 
-    @Parameter(name = ApiConstants.INTERNET_PROTOCOL,
-            type = CommandType.STRING,
-            description = "The internet protocol of the offering. Options are IPv4 and dualstack. Default is IPv4. dualstack will create an offering that supports both IPv4 and IPv6",
-            since = "4.17.0")
+    @Parameter(
+        name = ApiConstants.INTERNET_PROTOCOL,
+        type = CommandType.STRING,
+        description = "The internet protocol of the offering. Options are IPv4 and dualstack. Default is IPv4. dualstack will create an offering that supports both IPv4 and IPv6",
+        since = "4.17.0",
+        allowedValues = {
+                "IPv4",
+                "dualstack"
+        })
     private String internetProtocol;
 
     @Parameter(name = ApiConstants.SERVICE_OFFERING_ID,
@@ -144,10 +149,15 @@ public class CreateVPCOfferingCmd extends BaseAsyncCreateCmd {
             since = "4.16")
     private Boolean enable;
 
-    @Parameter(name = ApiConstants.NETWORK_MODE,
-            type = CommandType.STRING,
-            description = "Indicates the mode with which the network will operate. Valid option: NATTED or ROUTED",
-            since = "4.20.0")
+    @Parameter(
+        name = ApiConstants.NETWORK_MODE,
+        type = CommandType.STRING,
+        description = "Indicates the mode with which the network will operate. Valid option: NATTED or ROUTED",
+        since = "4.20.0",
+        allowedValues = {
+                "NATTED",
+                "ROUTED"
+        })
     private String networkMode;
 
     @Parameter(name = ApiConstants.SPECIFY_AS_NUMBER, type = CommandType.BOOLEAN, since = "4.20.0",

api/src/main/java/org/apache/cloudstack/api/command/user/backup/CreateBackupScheduleCmd.java

@@ -56,9 +56,15 @@ public class CreateBackupScheduleCmd extends BaseCmd {
     private Long vmId;
 
     @Parameter(name = ApiConstants.INTERVAL_TYPE,
-            type = CommandType.STRING,
-            required = true,
-            description = "Valid values are HOURLY, DAILY, WEEKLY, and MONTHLY")
+        type = CommandType.STRING,
+        required = true,
+        description = "Valid values are HOURLY, DAILY, WEEKLY, and MONTHLY",
+        allowedValues = {
+                "HOURLY",
+                "DAILY",
+                "WEEKLY",
+                "MONTHLY"
+        })
     private String intervalType;
 
     @Parameter(name = ApiConstants.SCHEDULE,

api/src/main/java/org/apache/cloudstack/api/command/user/firewall/CreateFirewallRuleCmd.java

@@ -61,9 +61,10 @@ public class CreateFirewallRuleCmd extends BaseAsyncCreateCmd implements Firewal
     private Long ipAddressId;
 
     @Parameter(name = ApiConstants.PROTOCOL,
-               type = CommandType.STRING,
-               required = true,
-               description = "The protocol for the firewall rule. Valid values are TCP/UDP/ICMP.")
+           type = CommandType.STRING,
+           required = true,
+           description = "The protocol for the firewall rule. Valid values are TCP/UDP/ICMP.",
+           allowedValues = {"TCP", "UDP", "ICMP"})
     private String protocol;
 
     @Parameter(name = ApiConstants.START_PORT, type = CommandType.INTEGER, description = "The starting port of firewall rule")

api/src/main/java/org/apache/cloudstack/api/command/user/ipv6/CreateIpv6FirewallRuleCmd.java

@@ -79,7 +79,14 @@ public class CreateIpv6FirewallRuleCmd extends BaseAsyncCreateCmd {
     @Parameter(name = ApiConstants.NETWORK_ID, type = CommandType.UUID, entityType = NetworkResponse.class, description = "The Network of the Instance the Ipv6 firewall rule will be created for", required = true)
     private Long networkId;
 
-    @Parameter(name = ApiConstants.TRAFFIC_TYPE, type = CommandType.STRING, description = "The traffic type for the Ipv6 firewall rule, can be ingress or egress, defaulted to ingress if not specified")
+    @Parameter(
+    name = ApiConstants.TRAFFIC_TYPE,
+    type = CommandType.STRING,
+    description = "The traffic type for the Ipv6 firewall rule, can be ingress or egress, defaulted to ingress if not specified",
+    allowedValues = {
+        "Ingress",
+        "Egress"
+    })
     private String trafficType;
 
     @Parameter(name = ApiConstants.FOR_DISPLAY, type = CommandType.BOOLEAN, description = "An optional field, whether to the display the rule to the end User or not", authorized = {RoleType.Admin})

api/src/main/java/org/apache/cloudstack/api/command/user/iso/ListIsosCmd.java

@@ -61,14 +61,24 @@ public class ListIsosCmd extends BaseListTaggedResourcesCmd implements UserCmd {
     private Boolean ready;
 
     @Parameter(name = ApiConstants.ISO_FILTER,
-               type = CommandType.STRING,
-               description = "Possible values are \"featured\", \"self\", \"selfexecutable\",\"sharedexecutable\",\"executable\", and \"community\". "
-                   + "* featured : Templates that have been marked as featured and public. "
-                   + "* self : Templates that have been registered or created by the calling User. "
-                   + "* selfexecutable : same as self, but only returns Templates that can be used to deploy a new Instance. "
-                   + "* sharedexecutable : Templates ready to be deployed that have been granted to the calling User by another User. "
-                   + "* executable : Templates that are owned by the calling User, or public Templates, that can be used to deploy an Instance. "
-                   + "* community : Templates that have been marked as public but not featured. " + "* all : all Templates (only usable by admins).")
+           type = CommandType.STRING,
+           description = "Possible values are \"featured\", \"self\", \"selfexecutable\",\"sharedexecutable\",\"executable\", and \"community\". "
+               + "* featured : Templates that have been marked as featured and public. "
+               + "* self : Templates that have been registered or created by the calling User. "
+               + "* selfexecutable : same as self, but only returns Templates that can be used to deploy a new Instance. "
+               + "* sharedexecutable : Templates ready to be deployed that have been granted to the calling User by another User. "
+               + "* executable : Templates that are owned by the calling User, or public Templates, that can be used to deploy an Instance. "
+               + "* community : Templates that have been marked as public but not featured. "
+               + "* all : all Templates (only usable by admins).",
+           allowedValues = {
+               "featured",
+               "self",
+               "selfexecutable",
+               "sharedexecutable",
+               "executable",
+               "community",
+               "all"
+           })
     private String isoFilter = TemplateFilter.selfexecutable.toString();
 
     @Parameter(name = ApiConstants.NAME, type = CommandType.STRING, description = "List all ISOs by name")
@@ -86,9 +96,15 @@ public class ListIsosCmd extends BaseListTaggedResourcesCmd implements UserCmd {
     @Parameter(name = ApiConstants.SHOW_RESOURCE_ICON, type = CommandType.BOOLEAN, description = "Flag to display the resource image for the ISOs")
     private Boolean showIcon;
 
-    @Parameter(name = ApiConstants.ARCH, type = CommandType.STRING,
-            description = "the CPU arch of the ISO. Valid options are: x86_64, aarch64, s390x",
-            since = "4.20")
+    @Parameter(name = ApiConstants.ARCH,
+        type = CommandType.STRING,
+        description = "the CPU arch of the ISO. Valid options are: x86_64, aarch64, s390x",
+        since = "4.20",
+        allowedValues = {
+            "x86_64",
+            "aarch64",
+            "s390x"
+        })
     private String arch;
 
     @Parameter(name = ApiConstants.OS_CATEGORY_ID, type = CommandType.UUID, entityType= GuestOSCategoryResponse.class,

api/src/main/java/org/apache/cloudstack/api/command/user/nat/CreateIpForwardingRuleCmd.java

@@ -63,7 +63,15 @@ public class CreateIpForwardingRuleCmd extends BaseAsyncCreateCmd implements Sta
     @Parameter(name = ApiConstants.END_PORT, type = CommandType.INTEGER, description = "The end port for the rule")
     private Integer endPort;
 
-    @Parameter(name = ApiConstants.PROTOCOL, type = CommandType.STRING, required = true, description = "The protocol for the rule. Valid values are TCP or UDP.")
+    @Parameter(
+    name = ApiConstants.PROTOCOL,
+    type = CommandType.STRING,
+    required = true,
+    description = "The protocol for the rule. Valid values are TCP or UDP.",
+    allowedValues = {
+        "TCP",
+        "UDP"
+    })
     private String protocol;
 
     @Parameter(name = ApiConstants.OPEN_FIREWALL,

api/src/main/java/org/apache/cloudstack/api/command/user/snapshot/CreateSnapshotPolicyCmd.java

@@ -52,7 +52,16 @@ public class CreateSnapshotPolicyCmd extends BaseCmd {
     //////////////// API parameters /////////////////////
     /////////////////////////////////////////////////////
 
-    @Parameter(name = ApiConstants.INTERVAL_TYPE, type = CommandType.STRING, required = true, description = "Valid values are HOURLY, DAILY, WEEKLY, and MONTHLY")
+    @Parameter(name = ApiConstants.INTERVAL_TYPE,
+            type = CommandType.STRING,
+            required = true,
+            description = "Valid values are HOURLY, DAILY, WEEKLY, and MONTHLY",
+            allowedValues = {
+                "HOURLY",
+                "DAILY",
+                "WEEKLY",
+                "MONTHLY"
+            })
     private String intervalType;
 
     @Parameter(name = ApiConstants.MAX_SNAPS, type = CommandType.INTEGER, required = true, description = "Maximum number of Snapshots to retain")

api/src/main/java/org/apache/cloudstack/api/command/user/snapshot/ListSnapshotsCmd.java

@@ -46,13 +46,27 @@ public class ListSnapshotsCmd extends BaseListTaggedResourcesCmd {
     @Parameter(name=ApiConstants.IDS, type=CommandType.LIST, collectionType=CommandType.UUID, entityType=SnapshotResponse.class, description = "The IDs of the Snapshots, mutually exclusive with id", since = "4.9")
     private List<Long> ids;
 
-    @Parameter(name = ApiConstants.INTERVAL_TYPE, type = CommandType.STRING, description = "Valid values are HOURLY, DAILY, WEEKLY, and MONTHLY.")
+    @Parameter(name = ApiConstants.INTERVAL_TYPE,
+        type = CommandType.STRING,
+        description = "Valid values are HOURLY, DAILY, WEEKLY, and MONTHLY.",
+        allowedValues = {
+                "HOURLY",
+                "DAILY",
+                "WEEKLY",
+                "MONTHLY"
+        })
     private String intervalType;
 
     @Parameter(name = ApiConstants.NAME, type = CommandType.STRING, description = "Lists Snapshot by Snapshot name")
     private String snapshotName;
 
-    @Parameter(name = ApiConstants.SNAPSHOT_TYPE, type = CommandType.STRING, description = "Valid values are MANUAL or RECURRING.")
+    @Parameter(name = ApiConstants.SNAPSHOT_TYPE,
+        type = CommandType.STRING,
+        description = "Valid values are MANUAL or RECURRING.",
+        allowedValues = {
+                "MANUAL",
+                "RECURRING"
+        })
     private String snapshotType;
 
     @Parameter(name = ApiConstants.VOLUME_ID, type = CommandType.UUID, entityType = VolumeResponse.class, description = "The ID of the disk volume")
@@ -64,8 +78,15 @@ public class ListSnapshotsCmd extends BaseListTaggedResourcesCmd {
     @Parameter(name = ApiConstants.SHOW_UNIQUE, type = CommandType.BOOLEAN, description = "If set to false, list templates across zones and their storages", since = "4.19.0")
     private Boolean showUnique;
 
-    @Parameter(name = ApiConstants.LOCATION_TYPE, type = CommandType.STRING, description = "list snapshots by location type. Used only when showunique=false. " +
-            "Valid location types: 'primary', 'secondary'. Default is empty", since = "4.19.0")
+    @Parameter(name = ApiConstants.LOCATION_TYPE,
+        type = CommandType.STRING,
+        description = "list snapshots by location type. Used only when showunique=false. "
+                + "Valid location types: 'primary', 'secondary'. Default is empty",
+        since = "4.19.0",
+        allowedValues = {
+                "primary",
+                "secondary"
+        })
     private String locationType;
 
     /////////////////////////////////////////////////////

api/src/main/java/org/apache/cloudstack/api/command/user/template/ListTemplatesCmd.java

@@ -67,15 +67,25 @@ public class ListTemplatesCmd extends BaseListTaggedResourcesCmd implements User
     private String templateName;
 
     @Parameter(name = ApiConstants.TEMPLATE_FILTER,
-               type = CommandType.STRING,
-               required = true,
-               description = "Possible values are \"featured\", \"self\", \"selfexecutable\",\"sharedexecutable\",\"executable\", and \"community\". "
-                   + "* featured : Templates that have been marked as featured and public. "
-                   + "* self : Templates that have been registered or created by the calling user. "
-                   + "* selfexecutable : same as self, but only returns Templates that can be used to deploy a new Instance. "
-                   + "* sharedexecutable : Templates ready to be deployed that have been granted to the calling user by another user. "
-                   + "* executable : Templates that are owned by the calling user, or public Templates, that can be used to deploy an Instance. "
-                   + "* community : Templates that have been marked as public but not featured. " + "* all : all Templates (only usable by admins).")
+           type = CommandType.STRING,
+           required = true,
+           description = "Possible values are \"featured\", \"self\", \"selfexecutable\", \"sharedexecutable\", \"executable\", and \"community\". "
+               + "* featured : Templates that have been marked as featured and public. "
+               + "* self : Templates that have been registered or created by the calling user. "
+               + "* selfexecutable : same as self, but only returns Templates that can be used to deploy a new Instance. "
+               + "* sharedexecutable : Templates ready to be deployed that have been granted to the calling user by another user. "
+               + "* executable : Templates that are owned by the calling user, or public Templates, that can be used to deploy an Instance. "
+               + "* community : Templates that have been marked as public but not featured. "
+               + "* all : all Templates (only usable by admins).",
+           allowedValues = {
+               "featured",
+               "self",
+               "selfexecutable",
+               "sharedexecutable",
+               "executable",
+               "community",
+               "all"
+           })
     private String templateFilter;
 
     @Parameter(name = ApiConstants.ZONE_ID, type = CommandType.UUID, entityType = ZoneResponse.class, description = "List Templates by zoneId")
@@ -111,9 +121,15 @@ public class ListTemplatesCmd extends BaseListTaggedResourcesCmd implements User
             since = "4.21.0")
     private Boolean forCks;
 
-    @Parameter(name = ApiConstants.ARCH, type = CommandType.STRING,
-            description = "the CPU arch of the template. Valid options are: x86_64, aarch64, s390x",
-            since = "4.20")
+    @Parameter(name = ApiConstants.ARCH,
+           type = CommandType.STRING,
+           description = "the CPU arch of the template. Valid options are: x86_64, aarch64, s390x",
+           since = "4.20",
+           allowedValues = {
+               "x86_64",
+               "aarch64",
+               "s390x"
+           })
     private String arch;
 
     @Parameter(name = ApiConstants.OS_CATEGORY_ID, type = CommandType.UUID, entityType = GuestOSCategoryResponse.class,

api/src/main/java/org/apache/cloudstack/api/command/user/template/RegisterTemplateCmd.java

@@ -67,9 +67,15 @@ public class RegisterTemplateCmd extends BaseCmd implements UserCmd {
     private String displayText;
 
     @Parameter(name = ApiConstants.FORMAT,
-               type = CommandType.STRING,
-               required = true,
-               description = "The format for the Template. Possible values include QCOW2, RAW, VHD and OVA.")
+           type = CommandType.STRING,
+           required = true,
+           description = "The format for the Template. Possible values include QCOW2, RAW, VHD and OVA.",
+           allowedValues = {
+               "QCOW2",
+               "RAW",
+               "VHD",
+               "OVA"
+           })
     private String format;
 
     @Parameter(name = ApiConstants.HYPERVISOR, type = CommandType.STRING, required = true, description = "The target hypervisor for the Template")
@@ -179,9 +185,15 @@ public class RegisterTemplateCmd extends BaseCmd implements UserCmd {
             since = "4.19.0")
     private String templateType;
 
-    @Parameter(name = ApiConstants.ARCH, type = CommandType.STRING,
-            description = "the CPU arch of the template. Valid options are: x86_64, aarch64, s390x",
-            since = "4.20")
+    @Parameter(name = ApiConstants.ARCH,
+           type = CommandType.STRING,
+           description = "the CPU arch of the template. Valid options are: x86_64, aarch64, s390x",
+           since = "4.20",
+           allowedValues = {
+               "x86_64",
+               "aarch64",
+               "s390x"
+           })
     private String arch;
 
     @Parameter(name = ApiConstants.EXTENSION_ID, type = CommandType.UUID, entityType = ExtensionResponse.class,

plugins/api/discovery/src/main/java/org/apache/cloudstack/api/response/ApiParameterResponse.java

@@ -54,6 +54,10 @@ public class ApiParameterResponse extends BaseResponse {
     @Param(description = "Comma separated related APIs to get the parameter")
     private String related;
 
+    @SerializedName("allowedvalues")
+    @Param(description = "List of allowed values for this parameter")
+    private List<String> allowedValues;
+
     private transient List<RoleType> authorizedRoleTypes = null;
 
     public ApiParameterResponse() {
@@ -91,6 +95,14 @@ public void setRelated(String related) {
         this.related = related;
     }
 
+    public List<String> getAllowedValues() {
+        return allowedValues;
+    }
+
+    public void setAllowedValues(List<String> allowedValues) {
+        this.allowedValues = allowedValues;
+    }
+
     public void setAuthorizedRoleTypes(List<RoleType> authorizedRoleTypes) {
         this.authorizedRoleTypes = authorizedRoleTypes;
     }

plugins/api/discovery/src/main/java/org/apache/cloudstack/discovery/ApiDiscoveryServiceImpl.java

@@ -19,6 +19,7 @@
 import java.lang.reflect.Field;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Iterator;
@@ -236,10 +237,19 @@ protected ApiDiscoveryResponse getCmdRequestMap(Class<?> cmdClass, APICommand ap
                     paramResponse.setSince(parameterAnnotation.since());
                 }
                 paramResponse.setRelated(parameterAnnotation.entityType()[0].getName());
-                if (parameterAnnotation.authorized() != null) {
-                    paramResponse.setAuthorizedRoleTypes(Arrays.asList(parameterAnnotation.authorized()));
-                }
-                response.addParam(paramResponse);
+
+            String[] allowedValues = parameterAnnotation.allowedValues();
+            if (allowedValues.length > 0) {
+                paramResponse.setAllowedValues(
+                    Collections.unmodifiableList(Arrays.asList(allowedValues))
+                );
+            }
+
+            if (parameterAnnotation.authorized() != null) {
+                paramResponse.setAuthorizedRoleTypes(Arrays.asList(parameterAnnotation.authorized()));
+            }
+
+            response.addParam(paramResponse);
             }
         }
         return response;

plugins/api/discovery/src/test/java/org/apache/cloudstack/discovery/ApiDiscoveryServiceImplTest.java

@@ -107,6 +107,7 @@ public void getCmdRequestMapAddsParamsWithExposedAndIncludedInApiDocAnnotations(
         Mockito.when(parameterMock.name()).thenReturn("paramName");
         Mockito.when(parameterMock.since()).thenReturn("");
         Mockito.when(parameterMock.entityType()).thenReturn(new Class[]{Object.class});
+        Mockito.when(parameterMock.allowedValues()).thenReturn(new String[]{});
         Mockito.when(parameterMock.description()).thenReturn("paramDescription");
         Mockito.when(parameterMock.type()).thenReturn(BaseCmd.CommandType.STRING);
         Mockito.when(fieldMock.getAnnotation(Parameter.class)).thenReturn(parameterMock);