Skip to content

API docs/generation improvements #12467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sureshanaparti wants to merge 2 commits into
base: main
Choose a base branch
from
+108 −501
Open

API docs/generation improvements #12467

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
958e1b4
API docs improvements
sureshanaparti Jan 5, 2026
5482fdf
improvements / cleanup
sureshanaparti Jan 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion api/src/main/java/org/apache/cloudstack/api/command/admin/storage/ListStorageTagsCmd.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {


Expand Down
2 changes: 1 addition & 1 deletion ...org/apache/cloudstack/network/opendaylight/api/commands/AddOpenDaylightControllerCmd.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
2 changes: 1 addition & 1 deletion .../apache/cloudstack/network/opendaylight/api/commands/DeleteOpenDaylightControllerCmd.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion ...g/apache/cloudstack/network/opendaylight/api/commands/ListOpenDaylightControllersCmd.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
86 changes: 7 additions & 79 deletions server/src/main/java/com/cloud/api/doc/ApiXmlDocWriter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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();
Expand All @@ -104,12 +97,8 @@ public static void main(String[] args) {
if (curCmd.isAssignableFrom(cmdClass)) {
// 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;
} else {
System.out.println("Warning, API Cmd class " + cmdClass.getName() + " has non-unique apiname " + apiName);
continue;
} else if (!cmdClass.isAssignableFrom(curCmd)) {
System.out.println("Warning: API Cmd class " + cmdClass.getName() + " has non-unique api name " + apiName);
}
} else {
s_apiNameCmdClassMap.put(apiName, cmdClass);
Expand Down Expand Up @@ -178,8 +167,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();
Expand Down Expand Up @@ -220,19 +207,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);
}
}

Expand Down Expand Up @@ -361,49 +348,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);
Expand All @@ -421,20 +365,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);
}
}
}
Loading
Loading