API docs improvements

- Proper category alignments during API docs generation
- Since attribute for API, Request & Response parameters
- Code improvements/cleanup

Author: sureshanaparti

api/src/main/java/org/apache/cloudstack/api/command/admin/storage/ListStorageTagsCmd.java

@@ -24,7 +24,7 @@
 import org.apache.cloudstack.api.response.ListResponse;
 import org.apache.cloudstack.api.response.StorageTagResponse;
 
-@APICommand(name = "listStorageTags", description = "Lists storage tags", responseObject = StorageTagResponse.class, requestHasSensitiveInfo = false, responseHasSensitiveInfo = false)
+@APICommand(name = "listStorageTags", description = "Lists storage pool tags", responseObject = StorageTagResponse.class, requestHasSensitiveInfo = false, responseHasSensitiveInfo = false)
 public class ListStorageTagsCmd extends BaseListCmd {
 
 

plugins/network-elements/opendaylight/src/main/java/org/apache/cloudstack/network/opendaylight/api/commands/AddOpenDaylightControllerCmd.java

@@ -38,7 +38,7 @@
 import com.cloud.exception.ResourceAllocationException;
 import com.cloud.exception.ResourceUnavailableException;
 
-@APICommand(name = "addOpenDaylightController", responseObject = OpenDaylightControllerResponse.class, description = "Adds an OpenDyalight controler",
+@APICommand(name = "addOpenDaylightController", responseObject = OpenDaylightControllerResponse.class, description = "Adds an OpenDaylight controller",
         requestHasSensitiveInfo = true, responseHasSensitiveInfo = false)
 public class AddOpenDaylightControllerCmd extends BaseAsyncCmd {
 

plugins/network-elements/opendaylight/src/main/java/org/apache/cloudstack/network/opendaylight/api/commands/DeleteOpenDaylightControllerCmd.java

@@ -40,7 +40,7 @@
 import com.cloud.exception.ResourceAllocationException;
 import com.cloud.exception.ResourceUnavailableException;
 
-@APICommand(name = "deleteOpenDaylightController", responseObject = OpenDaylightControllerResponse.class, description = "Removes an OpenDyalight controler",
+@APICommand(name = "deleteOpenDaylightController", responseObject = OpenDaylightControllerResponse.class, description = "Removes an OpenDaylight controller",
         requestHasSensitiveInfo = false, responseHasSensitiveInfo = false)
 public class DeleteOpenDaylightControllerCmd extends BaseAsyncCmd {
     @Inject

plugins/network-elements/opendaylight/src/main/java/org/apache/cloudstack/network/opendaylight/api/commands/ListOpenDaylightControllersCmd.java

@@ -42,7 +42,7 @@
 import com.cloud.exception.ResourceAllocationException;
 import com.cloud.exception.ResourceUnavailableException;
 
-@APICommand(name = "listOpenDaylightControllers", responseObject = OpenDaylightControllerResponse.class, description = "Lists OpenDyalight controllers",
+@APICommand(name = "listOpenDaylightControllers", responseObject = OpenDaylightControllerResponse.class, description = "Lists OpenDaylight controllers",
         requestHasSensitiveInfo = false, responseHasSensitiveInfo = false)
 public class ListOpenDaylightControllersCmd extends BaseCmd {
     @Inject

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

@@ -41,28 +41,21 @@
 import org.apache.logging.log4j.LogManager;
 
 import java.io.File;
-import java.io.FileInputStream;
-import java.io.FileOutputStream;
 import java.io.FileWriter;
 import java.io.IOException;
 import java.io.ObjectOutputStream;
 import java.lang.reflect.Field;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
-import java.util.Enumeration;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
-import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
-import java.util.Properties;
 import java.util.Set;
 import java.util.TreeMap;
-import java.util.zip.ZipEntry;
-import java.util.zip.ZipOutputStream;
 
 public class ApiXmlDocWriter {
     protected static Logger LOGGER = LogManager.getLogger(ApiXmlDocWriter.class);
@@ -93,8 +86,8 @@ public static void main(String[] args) {
                 "org.apache.cloudstack.api.command.admin.zone", "org.apache.cloudstack.network.contrail.api.command"});
 
         for (Class<?> cmdClass : cmdClasses) {
-            if(cmdClass.getAnnotation(APICommand.class)==null){
-               System.out.println("Warning, API Cmd class " + cmdClass.getName() + " has no APICommand annotation ");
+            if (cmdClass.getAnnotation(APICommand.class) == null) {
+               System.out.println("Warning: API Cmd class " + cmdClass.getName() + " has no APICommand annotation ");
                continue;
             }
             String apiName = cmdClass.getAnnotation(APICommand.class).name();
@@ -105,11 +98,9 @@ public static void main(String[] args) {
                     // api_cmd map always keep the admin cmd class to get full response and parameters
                     s_apiNameCmdClassMap.put(apiName, cmdClass);
                 } else if (cmdClass.isAssignableFrom(curCmd)) {
-                    // just skip this one without warning
-                    continue;
+                    System.out.println("Info: API Cmd class " + cmdClass.getName() + " is assignable from " + curCmd.getName() + ", skip this one");
                 } else {
-                    System.out.println("Warning, API Cmd class " + cmdClass.getName() + " has non-unique apiname " + apiName);
-                    continue;
+                    System.out.println("Warning: API Cmd class " + cmdClass.getName() + " has non-unique apiname " + apiName);
                 }
             } else {
                 s_apiNameCmdClassMap.put(apiName, cmdClass);
@@ -178,8 +169,6 @@ public static void main(String[] args) {
 
     private static void writeCommand(ObjectOutputStream out, String command) throws ClassNotFoundException, IOException {
         Class<?> clas = Class.forName(s_allApiCommands.get(command));
-        ArrayList<Argument> request = new ArrayList<Argument>();
-        ArrayList<Argument> response = new ArrayList<Argument>();
 
         // Create a new command, set name/description/usage
         Command apiCommand = new Command();
@@ -220,19 +209,19 @@ private static void writeCommand(ObjectOutputStream out, String command) throws
 
             Set<Field> fields = ReflectUtil.getAllFieldsForClass(clas, new Class<?>[] {BaseCmd.class, BaseAsyncCmd.class, BaseAsyncCreateCmd.class});
 
-            request = setRequestFields(fields);
+            ArrayList<Argument> request = setRequestFields(fields);
 
             // Get response parameters
             Class<?> responseClas = impl.responseObject();
             Field[] responseFields = responseClas.getDeclaredFields();
-            response = setResponseFields(responseFields, responseClas);
+            ArrayList<Argument> response = setResponseFields(responseFields, responseClas);
 
             apiCommand.setRequest(request);
             apiCommand.setResponse(response);
 
             out.writeObject(apiCommand);
         } else {
-            LOGGER.debug("Command " + command + " is not exposed in api doc");
+            LOGGER.debug("Command {} is not exposed in api doc", command);
         }
     }
 
@@ -361,49 +350,6 @@ private static ArrayList<Argument> setResponseFields(Field[] responseFields, Cla
         return arguments;
     }
 
-    private static void zipDir(String zipFileName, String dir) throws Exception {
-        File dirObj = new File(dir);
-        ZipOutputStream out = new ZipOutputStream(new FileOutputStream(zipFileName));
-        addDir(dirObj, out);
-        out.close();
-    }
-
-    static void addDir(File dirObj, ZipOutputStream out) throws IOException {
-        File[] files = dirObj.listFiles();
-        byte[] tmpBuf = new byte[1024];
-        String pathToDir = s_dirName;
-
-        for (int i = 0; i < files.length; i++) {
-            if (files[i].isDirectory()) {
-                addDir(files[i], out);
-                continue;
-            }
-            try(FileInputStream in = new FileInputStream(files[i].getPath());) {
-                out.putNextEntry(new ZipEntry(files[i].getPath().substring(pathToDir.length())));
-                int len;
-                while ((len = in.read(tmpBuf)) > 0) {
-                    out.write(tmpBuf, 0, len);
-                }
-                out.closeEntry();
-            }catch(IOException ex)
-            {
-                LOGGER.error("addDir:Exception:"+ ex.getMessage(),ex);
-            }
-        }
-    }
-
-    private static void deleteDir(File dir) {
-        if (dir.isDirectory()) {
-            String[] children = dir.list();
-            if (children != null) {
-                for (int i = 0; i < children.length; i++) {
-                    deleteDir(new File(dir, children[i]));
-                }
-            }
-        }
-        dir.delete();
-    }
-
     private static void writeAlertTypes(String dirName) {
         XStream xs = new XStream();
         xs.alias("alert", Alert.class);
@@ -421,20 +367,4 @@ private static void writeAlertTypes(String dirName) {
             LOGGER.error("Failed to read alert fields ", e);
         }
     }
-
-    private static class LinkedProperties extends Properties {
-        private final LinkedList<Object> keys = new LinkedList<Object>();
-
-        @Override
-        public Enumeration<Object> keys() {
-            return Collections.<Object> enumeration(keys);
-        }
-
-        @Override
-        public Object put(Object key, Object value) {
-            // System.out.println("Adding key" + key);
-            keys.add(key);
-            return super.put(key, value);
-        }
-    }
 }