diff --git a/api/src/com/cloud/api/commands/CreateTemplateCmd.java b/api/src/com/cloud/api/commands/CreateTemplateCmd.java index 2dc17f684da..6e30653d24c 100644 --- a/api/src/com/cloud/api/commands/CreateTemplateCmd.java +++ b/api/src/com/cloud/api/commands/CreateTemplateCmd.java @@ -47,7 +47,7 @@ public class CreateTemplateCmd extends BaseAsyncCreateCmd { //////////////// API parameters ///////////////////// ///////////////////////////////////////////////////// - @Parameter(name=ApiConstants.BITS, type=CommandType.INTEGER) + @Parameter(name=ApiConstants.BITS, type=CommandType.INTEGER, description="32 or 64 bit") private Integer bits; @Parameter(name=ApiConstants.DISPLAY_TEXT, type=CommandType.STRING, required=true, description="the display text of the template. This is usually used for display purposes.") diff --git a/api/src/com/cloud/api/commands/RegisterPreallocatedLunCmd.java b/api/src/com/cloud/api/commands/RegisterPreallocatedLunCmd.java index e7d7f72d118..d3aca457b2c 100644 --- a/api/src/com/cloud/api/commands/RegisterPreallocatedLunCmd.java +++ b/api/src/com/cloud/api/commands/RegisterPreallocatedLunCmd.java @@ -33,20 +33,17 @@ public class RegisterPreallocatedLunCmd extends BaseCmd { //////////////// API parameters ///////////////////// ///////////////////////////////////////////////////// - //FIXME - add description - @Parameter(name=ApiConstants.DISK_SIZE, type=CommandType.LONG, required=true) + @Parameter(name=ApiConstants.DISK_SIZE, type=CommandType.LONG, required=true, description="Volume size") private Long diskSize; - //FIXME - add description - @Parameter(name=ApiConstants.LUN, type=CommandType.INTEGER, required=true) + @Parameter(name=ApiConstants.LUN, type=CommandType.INTEGER, required=true, description="Lun id") private Integer lun; //FIXME - add description @Parameter(name=ApiConstants.PORTAL, type=CommandType.STRING, required=true) private String portal; - //FIXME - add description - @Parameter(name=ApiConstants.TAGS, type=CommandType.STRING) + @Parameter(name=ApiConstants.TAGS, type=CommandType.STRING, description="tags for the volume") private String tags; @Parameter(name=ApiConstants.TARGET_IQN, type=CommandType.STRING, required=true, description="the target IQN on the storage host where LUN is created") diff --git a/api/src/com/cloud/api/response/DiskOfferingResponse.java b/api/src/com/cloud/api/response/DiskOfferingResponse.java index 8d20d06c5ab..32c123431ad 100644 --- a/api/src/com/cloud/api/response/DiskOfferingResponse.java +++ b/api/src/com/cloud/api/response/DiskOfferingResponse.java @@ -45,10 +45,7 @@ public class DiskOfferingResponse extends BaseResponse { @SerializedName(ApiConstants.CREATED) @Param(description="the date this disk offering was created") private Date created; - @SerializedName("ismirrored") - private Boolean mirrored; - - @SerializedName("iscustomized") + @SerializedName("iscustomized") @Param(description="true if disk offering uses custom size, false otherwise") private Boolean customized; @SerializedName(ApiConstants.TAGS) @Param(description="the tags for the disk offering") @@ -110,14 +107,6 @@ public class DiskOfferingResponse extends BaseResponse { this.created = created; } - public Boolean isMirrored() { - return mirrored; - } - - public void setMirrored(Boolean mirrored) { - this.mirrored = mirrored; - } - public String getTags() { return tags; } diff --git a/api/src/com/cloud/api/response/ExtractResponse.java b/api/src/com/cloud/api/response/ExtractResponse.java index 6c9f2dae1b9..2190a6b4863 100755 --- a/api/src/com/cloud/api/response/ExtractResponse.java +++ b/api/src/com/cloud/api/response/ExtractResponse.java @@ -42,7 +42,7 @@ public class ExtractResponse extends BaseResponse { @SerializedName("accountid") @Param(description="the account id to which the extracted object belongs") private Long accountId; - @SerializedName("resultstring") @Param(description="") + @SerializedName("resultstring") @Param(expose=false) private String resultString; @SerializedName(ApiConstants.CREATED) @Param(description="the time and date the object was created") @@ -51,11 +51,9 @@ public class ExtractResponse extends BaseResponse { @SerializedName(ApiConstants.STATE) @Param(description="the state of the extracted object") private String state; - //FIXME - add description - @SerializedName("storagetype") + @SerializedName("storagetype") @Param(description="type of the storage") private String storageType; - //FIXME - add description @SerializedName("storage") private String storage; diff --git a/api/src/com/cloud/api/response/HypervisorResponse.java b/api/src/com/cloud/api/response/HypervisorResponse.java index 3fd675e98b2..ff9d52a10a0 100644 --- a/api/src/com/cloud/api/response/HypervisorResponse.java +++ b/api/src/com/cloud/api/response/HypervisorResponse.java @@ -1,10 +1,11 @@ package com.cloud.api.response; import com.cloud.api.ApiConstants; +import com.cloud.serializer.Param; import com.google.gson.annotations.SerializedName; public class HypervisorResponse extends BaseResponse { - @SerializedName(ApiConstants.NAME) + @SerializedName(ApiConstants.NAME) @Param(description="Hypervisor name") private String name; public String getName() { diff --git a/api/src/com/cloud/api/response/NetworkResponse.java b/api/src/com/cloud/api/response/NetworkResponse.java index 0c1df19f4e9..1ea5540ad84 100644 --- a/api/src/com/cloud/api/response/NetworkResponse.java +++ b/api/src/com/cloud/api/response/NetworkResponse.java @@ -3,6 +3,7 @@ package com.cloud.api.response; import java.util.List; import com.cloud.api.ApiConstants; +import com.cloud.network.Networks; import com.cloud.serializer.Param; import com.google.gson.annotations.SerializedName; @@ -17,20 +18,16 @@ public class NetworkResponse extends BaseResponse{ @SerializedName("displaytext") @Param(description="the displaytext of the network") private String displaytext; - //TODO - add description - @SerializedName("broadcastdomaintype") + @SerializedName("broadcastdomaintype") @Param(description="Broadcast domain type of the network") private String broadcastDomainType; - //TODO - add description - @SerializedName("traffictype") + @SerializedName("traffictype") @Param(description="the traffic type of the network") private String trafficType; - //TODO - add description - @SerializedName("gateway") + @SerializedName("gateway") @Param(description="the network's gateway") private String gateway; - //TODO - add description - @SerializedName("netmask") + @SerializedName("netmask") @Param(description="the network's netmask") private String netmask; @SerializedName("startip") @Param(description="the start ip of the network") @@ -39,61 +36,47 @@ public class NetworkResponse extends BaseResponse{ @SerializedName("endip") @Param(description="the end ip of the network") private String endIp; - //TODO - add description - @SerializedName("zoneid") + @SerializedName("zoneid") @Param(description="zone id of the network") private Long zoneId; - //TODO - add description - @SerializedName("networkofferingid") + @SerializedName("networkofferingid") @Param(description="network offering id the network is created from") private Long networkOfferingId; - //TODO - add description - @SerializedName("networkofferingname") + @SerializedName("networkofferingname") @Param(description="name of the network offering the network is created from") private String networkOfferingName; - //TODO - add description - @SerializedName("networkofferingdisplaytext") + @SerializedName("networkofferingdisplaytext") @Param(description="display text of the network offering the network is created from") private String networkOfferingDisplayText; - //TODO - add description - @SerializedName("networkofferingavailability") + @SerializedName("networkofferingavailability") @Param(description="availability of the network offering the network is created from") private String networkOfferingAvailability; - - //TODO - add description - @SerializedName("isshared") + @SerializedName("isshared") @Param(description="true if network is shared, false otherwise") private Boolean isShared; - //TODO - add description - @SerializedName("issystem") + @SerializedName("issystem") @Param(description="true if network is system, false otherwise") private Boolean isSystem; - //TODO - add description - @SerializedName("state") + @SerializedName("state") @Param(description="state of the network") private String state; //TODO - add description @SerializedName("related") private Long related; - //TODO - add description - @SerializedName("broadcasturi") + @SerializedName("broadcasturi") @Param(description="broadcast uri of the network") private String broadcastUri; - //TODO - add description - @SerializedName("dns1") + @SerializedName("dns1") @Param(description="the first dns for the network") private String dns1; - //TODO - add description - @SerializedName("dns2") + @SerializedName("dns2") @Param(description="the second dns for the network") private String dns2; - //TODO - add description - @SerializedName("type") + @SerializedName("type") @Param(description="the type of the network") private String type; - //TODO - add description - @SerializedName("vlan") + @SerializedName("vlan") @Param(description="the vlan of the network") private String vlan; @SerializedName(ApiConstants.ACCOUNT) @Param(description="the account associated with the network") diff --git a/api/src/com/cloud/api/response/VolumeResponse.java b/api/src/com/cloud/api/response/VolumeResponse.java index 481b0a640f3..f415077a648 100644 --- a/api/src/com/cloud/api/response/VolumeResponse.java +++ b/api/src/com/cloud/api/response/VolumeResponse.java @@ -81,13 +81,13 @@ public class VolumeResponse extends BaseResponse { @SerializedName("storagetype") @Param(description="shared or local storage") private String storageType; - @SerializedName("sourceid") + @SerializedName("sourceid") @Param(description="Id of the snapshot or diskOffering volume is created from") private Long sourceId; - @SerializedName("sourcetype") + @SerializedName("sourcetype") @Param(description="Type of the source the volume is created from. Can be: Snapshot,DiskOffering") private String sourceType; - @SerializedName(ApiConstants.HYPERVISOR) + @SerializedName(ApiConstants.HYPERVISOR) @Param(description="Hypervisor the volume belongs to") private String hypervisor; @SerializedName(ApiConstants.DISK_OFFERING_ID) @Param(description="ID of the disk offering") diff --git a/api/src/com/cloud/api/response/ZoneResponse.java b/api/src/com/cloud/api/response/ZoneResponse.java index daa40c07483..efbd044d892 100644 --- a/api/src/com/cloud/api/response/ZoneResponse.java +++ b/api/src/com/cloud/api/response/ZoneResponse.java @@ -42,19 +42,18 @@ public class ZoneResponse extends BaseResponse { @SerializedName(ApiConstants.INTERNAL_DNS2) @Param(description="the second internal DNS for the Zone") private String internalDns2; - - //FIXME - add description. This parameter is called "vnet" in updateZone, and vlan in createZone - figure out which one is right. - @SerializedName(ApiConstants.VLAN) + + @SerializedName(ApiConstants.VLAN) @Param(description="the vlan range of the zone") private String vlan; @SerializedName(ApiConstants.GUEST_CIDR_ADDRESS) @Param(description="the guest CIDR address for the Zone") private String guestCidrAddress; - //FIXME - do we need 2 parameters below at all? + //TODO - generate description @SerializedName("status") private String status; - @SerializedName(ApiConstants.DISPLAY_TEXT) + @SerializedName(ApiConstants.DISPLAY_TEXT) @Param(description="the display text of the zone") private String displayText; @SerializedName(ApiConstants.DOMAIN) @Param(description="Domain name for the Vms in the zone") diff --git a/api/src/com/cloud/serializer/Param.java b/api/src/com/cloud/serializer/Param.java index da3579e3125..cf119a2de1b 100644 --- a/api/src/com/cloud/serializer/Param.java +++ b/api/src/com/cloud/serializer/Param.java @@ -25,5 +25,6 @@ import java.lang.annotation.RetentionPolicy; public @interface Param { String name() default ""; String propName() default ""; - String description() default ""; + String description() default ""; + boolean expose() default true; } diff --git a/server/src/com/cloud/api/doc/ApiXmlDocReader.java b/server/src/com/cloud/api/doc/ApiXmlDocReader.java index 9d8272ef4cc..54f9627478d 100644 --- a/server/src/com/cloud/api/doc/ApiXmlDocReader.java +++ b/server/src/com/cloud/api/doc/ApiXmlDocReader.java @@ -203,7 +203,11 @@ public class ApiXmlDocReader { StringBuffer newParameters = new StringBuffer(); newParameters.append("\n\t\t\tNew parameters: "); for (Argument newArg: newReqArgs) { - newParameters.append(newArg.getName() + ", "); + String isRequiredParam = "optional"; + if (newArg.isRequired()) { + isRequiredParam = "required"; + } + newParameters.append(newArg.getName() + " (" + isRequiredParam + "), "); } newParameters.delete(newParameters.length()-2, newParameters.length()-1); out.write(newParameters.toString()); diff --git a/server/src/com/cloud/api/doc/ApiXmlDocWriter.java b/server/src/com/cloud/api/doc/ApiXmlDocWriter.java index 712835f127d..70e602bcdb8 100644 --- a/server/src/com/cloud/api/doc/ApiXmlDocWriter.java +++ b/server/src/com/cloud/api/doc/ApiXmlDocWriter.java @@ -108,7 +108,11 @@ public class ApiXmlDocWriter { String commandName = commandParts[0]; all_api_commands.put(key, commandName); - short cmdPermissions = Short.parseShort(commandParts[1]); + short cmdPermissions = 1; + if (commandParts.length > 1 && commandParts[1] != null) { + cmdPermissions = Short.parseShort(commandParts[1]); + } + if ((cmdPermissions & DOMAIN_ADMIN_COMMAND) != 0) { domain_admin_api_commands.put(key, commandName); } @@ -245,13 +249,13 @@ public class ApiXmlDocWriter { for (Field f : fields) { Parameter parameterAnnotation = f.getAnnotation(Parameter.class); - if (parameterAnnotation != null) { + if (parameterAnnotation != null && parameterAnnotation.expose()) { Argument reqArg = new Argument(parameterAnnotation.name()); reqArg.setRequired(parameterAnnotation.required()); - if (!parameterAnnotation.description().isEmpty() && parameterAnnotation.expose()) + if (!parameterAnnotation.description().isEmpty()) reqArg.setDescription(parameterAnnotation.description()); - else if (parameterAnnotation.expose()) { - //System.out.println("Description is missing for the parameter " + parameterAnnotation.name() + " of the command " + apiCommand.getName() ); + else { + //System.out.println("Description is missing for the request parameter " + parameterAnnotation.name() + " of the command " + apiCommand.getName()); } request.add(reqArg); } @@ -261,13 +265,26 @@ public class ApiXmlDocWriter { //Get response parameters Field[] responseFields = responseClas.getDeclaredFields(); - for (Field responseField : responseFields) { + for (Field responseField : responseFields) { SerializedName nameAnnotation = responseField.getAnnotation(SerializedName.class); Param descAnnotation = responseField.getAnnotation(Param.class); - Argument respArg = new Argument(nameAnnotation.value()); - if (descAnnotation != null) - respArg.setDescription(descAnnotation.description()); - response.add(respArg); + Argument respArg = new Argument(nameAnnotation.value()); + boolean toExpose = true; + if (descAnnotation != null) { + String description = descAnnotation.description(); + toExpose = descAnnotation.expose(); + if (description != null && !description.isEmpty()) { + respArg.setDescription(description); + } else if (toExpose){ + //System.out.println("Description is missing for the response parameter " + nameAnnotation.value().toString() + " of the command " + apiCommand.getName()); + } + } else { + //System.out.println("Description is missing for the response parameter " + nameAnnotation.value().toString() + " of the command " + apiCommand.getName()); + } + + if (toExpose) { + response.add(respArg); + } } apiCommand.setRequest(request);