How we make API references.
How do we create API documentation for CloudStack?
Engineers include descriptive annotations when they write code. In Java, annotations start with @.
Some of the annotations we have defined to contain documentation strings look like this:
@Implementation(description="Creates an account", responseObject=UserResponse.class)
public class CreateAccountCmd extends BaseCmd {
public static final Logger s_logger = Logger.getLogger(CreateAccountCmd.class.getName());
private static final String s_name = "createaccountresponse";
/////////////////////////////////////////////////////
//////////////// API parameters /////////////////////
/////////////////////////////////////////////////////
@Parameter(name=ApiConstants.ACCOUNT, type=CommandType.STRING,
description="Creates the user under the specified account.")
private String accountName;
See the description=" " inside @Implementation and @Parameter. That text will be extracted in the Java to HTML step.
For more information, see Annotations in the API.
There is one piece of code that converts the Java annotations to XML output. Then there is another piece of code that takes in the XML for the table of contents as well as each command, and generates the HTML documents which we upload to our website.
The API doc building script is located at:
setup/apidoc/build-apidoc.sh
It calls the following to create intermediate XML output:
server/src/com/cloud/api/doc/ApiXmlDocWriter.java
After creating the XML files with ApiXmlDocWriter, the script calls the following:
setup/apidoc/XmlToHtmlConverter.java
This XmlToHtmlConverter uses a series of .xsl transforms (aka style sheets) to convert the XML to HTML. Those .xsl’s are all stored in:
setup/apidoc/*.xsl
The API documentation can be built with Maven using the following commands (should work on 4.1 and above). The belt-and-braces approach which always work is to build everything:
However if you've just edited the .xsl files since building you can use:
The built documentation can then be found here: tools/apidoc/target/xmldoc/html
The ApiXmlDocReader class will read and generate a text file of the difference between two versions of the API XML documents of Apache CloudStack. It needs access to the Xstream and the ApiXmlDocReader class.
You can call it with the following command:
java -cp ~/.m2/repository/com/thoughtworks/xstream/xstream/1.4.10/xstream-1.4.10.jar:/path/to/source/cloudstack/dist/rpmbuild/BUILD/cloudstack-4.12.0-SNAPSHOT/server/target/classes \ com.cloud.api.doc.ApiXmlDocReader -old /path/to/4.11.commands.xml -new /path/to/4.12.commands.xml -d /path/to/diff/
You'll find diff.txt in /path/to/diff/diff.txt which will contain the changes between the two files.