bug 9026: added ability to turn off apiCommand/commandParameter for docGeneration

status 9026: resolved fixed

1) Don't expose following commands in doc:

* registerSSHKeyPair
* createSSHKeyPair
* deleteSSHKeyPair
* listSSHKeyPairs

2) Don't show "sshKeyPairName" parameter for deployVm command

api/src/com/cloud/api/Implementation.java

@@ -11,4 +11,5 @@ import java.lang.annotation.Target;
 public @interface Implementation {
     Class<?> responseObject();
     String description() default "";
+    boolean includeInApiDoc() default true;
 }

api/src/com/cloud/api/Parameter.java

@@ -35,5 +35,6 @@ public @interface Parameter {
     CommandType type() default CommandType.OBJECT;
     CommandType collectionType() default CommandType.OBJECT;
     boolean expose() default true;
+    boolean includeInApiDoc() default true;
 }
 

api/src/com/cloud/api/commands/CreateSSHKeyPairCmd.java

@@ -11,7 +11,7 @@ import com.cloud.user.Account;
 import com.cloud.user.SSHKeyPair;
 import com.cloud.user.UserContext;
 
-@Implementation(description="Create a new keypair and returns the private key", responseObject=SSHKeyPairResponse.class) 
+@Implementation(description="Create a new keypair and returns the private key", responseObject=SSHKeyPairResponse.class, includeInApiDoc=false) 
 public class CreateSSHKeyPairCmd extends BaseCmd {
     public static final Logger s_logger = Logger.getLogger(CreateSSHKeyPairCmd.class.getName());
     private static final String s_name = "createkeypairresponse";

api/src/com/cloud/api/commands/DeleteSSHKeyPairCmd.java

@@ -10,7 +10,7 @@ import com.cloud.api.response.SuccessResponse;
 import com.cloud.user.Account;
 import com.cloud.user.UserContext;
 
-@Implementation(description="Deletes a keypair by name", responseObject=SuccessResponse.class) 
+@Implementation(description="Deletes a keypair by name", responseObject=SuccessResponse.class, includeInApiDoc=false) 
 public class DeleteSSHKeyPairCmd extends BaseCmd {
     public static final Logger s_logger = Logger.getLogger(CreateSSHKeyPairCmd.class.getName());
     private static final String s_name = "deletekeypairresponse";

api/src/com/cloud/api/commands/DeployVMCmd.java

@@ -100,7 +100,7 @@ public class DeployVMCmd extends BaseAsyncCreateCmd {
     @Parameter(name=ApiConstants.USER_DATA, type=CommandType.STRING, description="an optional binary data that can be sent to the virtual machine upon a successful deployment. This binary data must be base64 encoded before adding it to the request. Currently only HTTP GET is supported. Using HTTP GET (via querystring), you can send up to 2KB of data after base64 encoding.")
     private String userData;
 
-    @Parameter(name=ApiConstants.SSH_KEYPAIR, type=CommandType.STRING, description="name of the ssh key pair used to login to the virtual machine")
+    @Parameter(name=ApiConstants.SSH_KEYPAIR, type=CommandType.STRING, description="name of the ssh key pair used to login to the virtual machine", includeInApiDoc=false)
     private String sshKeyPairName;
     
     /////////////////////////////////////////////////////

api/src/com/cloud/api/commands/GetVMPasswordCmd.java

@@ -12,7 +12,7 @@ import com.cloud.api.response.GetVMPasswordResponse;
 import com.cloud.user.Account;
 import com.cloud.uservm.UserVm;
 
-@Implementation(responseObject=GetVMPasswordResponse.class, description="Returns an encrypted password for the VM")
+@Implementation(responseObject=GetVMPasswordResponse.class, description="Returns an encrypted password for the VM", includeInApiDoc=false)
 public class GetVMPasswordCmd extends BaseCmd {
     public static final Logger s_logger = Logger.getLogger(GetVMPasswordCmd.class.getName());
     private static final String s_name = "getvmpasswordresponse";

api/src/com/cloud/api/commands/ListSSHKeyPairsCmd.java

@@ -13,7 +13,7 @@ import com.cloud.api.response.ListResponse;
 import com.cloud.api.response.SSHKeyPairResponse;
 import com.cloud.user.SSHKeyPair;
 
-@Implementation(description="List registered keypairs", responseObject=SSHKeyPairResponse.class) 
+@Implementation(description="List registered keypairs", responseObject=SSHKeyPairResponse.class, includeInApiDoc=false) 
 public class ListSSHKeyPairsCmd extends BaseListCmd {
     public static final Logger s_logger = Logger.getLogger(ListSSHKeyPairsCmd.class.getName());
     private static final String s_name = "listsshkeypairsresponse";

api/src/com/cloud/api/commands/RegisterSSHKeyPairCmd.java

@@ -11,7 +11,7 @@ import com.cloud.user.Account;
 import com.cloud.user.SSHKeyPair;
 import com.cloud.user.UserContext;
 
-@Implementation(description="Register a public key in a keypair under a certain name", responseObject=SSHKeyPairResponse.class) 
+@Implementation(description="Register a public key in a keypair under a certain name", responseObject=SSHKeyPairResponse.class, includeInApiDoc=false) 
 public class RegisterSSHKeyPairCmd extends BaseCmd {
     public static final Logger s_logger = Logger.getLogger(RegisterSSHKeyPairCmd.class.getName());
     private static final String s_name = "registerkeypairresponse";

server/src/com/cloud/api/doc/ApiXmlDocWriter.java

@@ -287,49 +287,55 @@ public class ApiXmlDocWriter {
         apiCommand.setName(command);
         
         Implementation impl = (Implementation)clas.getAnnotation(Implementation.class);
-        if (impl == null)
+        if (impl == null) {
             impl = (Implementation)clas.getSuperclass().getAnnotation(Implementation.class);
-        String commandDescription = impl.description();
+        }
-        if (commandDescription != null)
-            apiCommand.setDescription(commandDescription);
-        else
-            System.out.println("Command " + apiCommand.getName() + " misses description");
             
-        //Set request parameters   
+        if (impl.includeInApiDoc()) {
-        Field[] fields = clas.getDeclaredFields();
+            String commandDescription = impl.description();
+            if (commandDescription != null)
+                apiCommand.setDescription(commandDescription);
+            else
+                System.out.println("Command " + apiCommand.getName() + " misses description");
             
-        //Get fields from superclass
+            //Set request parameters   
-        Class<?> superClass = clas.getSuperclass();
+            Field[] fields = clas.getDeclaredFields();
-        String superName = superClass.getName();
+            
-        if (!superName.equals(BaseCmd.class.getName()) && !superName.equals(BaseAsyncCmd.class.getName()) && !superName.equals(BaseAsyncCreateCmd.class.getName())) {
+            //Get fields from superclass
-            Field[] superClassFields = superClass.getDeclaredFields();
+            Class<?> superClass = clas.getSuperclass();
-            if (superClassFields != null && !superClass.getName().equals(BaseListCmd.class.getName())) {
+            String superName = superClass.getName();
-                Field[] tmpFields = new Field[fields.length + superClassFields.length];
+            if (!superName.equals(BaseCmd.class.getName()) && !superName.equals(BaseAsyncCmd.class.getName()) && !superName.equals(BaseAsyncCreateCmd.class.getName())) {
-                System.arraycopy(fields, 0, tmpFields, 0, fields.length);
+                Field[] superClassFields = superClass.getDeclaredFields();
-                System.arraycopy(superClassFields, 0, tmpFields, fields.length, superClassFields.length);
+                if (superClassFields != null && !superClass.getName().equals(BaseListCmd.class.getName())) {
-                fields = tmpFields;
+                    Field[] tmpFields = new Field[fields.length + superClassFields.length];
+                    System.arraycopy(fields, 0, tmpFields, 0, fields.length);
+                    System.arraycopy(superClassFields, 0, tmpFields, fields.length, superClassFields.length);
+                    fields = tmpFields;
+                }
+                superClass = superClass.getSuperclass();
             }
-            superClass = superClass.getSuperclass();
+            request = setRequestFields(fields);
-        }
-        request = setRequestFields(fields);
             
             
-        //Set Async information for the command
+            //Set Async information for the command
-        if (superName.equals(BaseAsyncCmd.class.getName()) || superName.equals(BaseAsyncCreateCmd.class.getName())) {
+            if (superName.equals(BaseAsyncCmd.class.getName()) || superName.equals(BaseAsyncCreateCmd.class.getName())) {
-            apiCommand.setAsync(true);
+                apiCommand.setAsync(true);
+            } else {
+                apiCommand.setAsync(false);
+            }
+            
+            //Get response parameters
+            Class<?> responseClas = impl.responseObject();
+            Field[] responseFields = responseClas.getDeclaredFields();
+            response = setResponseFields(responseFields);
+            
+            apiCommand.setRequest(request);
+            apiCommand.setResponse(response);
+            
+            out.writeObject(apiCommand);
         } else {
-            apiCommand.setAsync(false);
+            s_logger.debug("Command " + command + " is not exposed in api doc");
         }
-        
-        //Get response parameters
-        Class<?> responseClas = impl.responseObject();
-        Field[] responseFields = responseClas.getDeclaredFields();
-        response = setResponseFields(responseFields);
-        
-        apiCommand.setRequest(request);
-        apiCommand.setResponse(response);
-        
-        out.writeObject(apiCommand);
 	}
 	
 	private static void writeLoginCommand(ObjectOutputStream out) throws ClassNotFoundException, IOException{
@@ -394,7 +400,7 @@ public class ApiXmlDocWriter {
 	    Argument id = null;
 	    for (Field f : fields) {
             Parameter parameterAnnotation = f.getAnnotation(Parameter.class);
-            if (parameterAnnotation != null && parameterAnnotation.expose()) {
+            if (parameterAnnotation != null && parameterAnnotation.expose() && parameterAnnotation.includeInApiDoc()) {
                 Argument reqArg = new Argument(parameterAnnotation.name());
                 reqArg.setRequired(parameterAnnotation.required());
                 if (!parameterAnnotation.description().isEmpty()) {