How we make API references. Under construction.

Overview

How do we create API documentation for CloudStack?

1. Java Annotations in API code.
2. Cosmetic touch-ups in doc generation code.
3. Java to HTML using Jenkins.

Annotations

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.

API command annotations">API command annotations

Each API command should include following annotations:

@Implementation - command level @. Used by the API doc builder only

Fields:

• description (String, empty if not specified) - provides brief description for the API command.
• usage (String, empty if not specified) - gives the example of the command usage (supported parameters combinations, any other details that are too big to be included to the description)
• includeInApiDoc (boolean, true if not specified) - defines if the command should be included to the API doc
• since (String, empty if not specified) - mentions the product version the command was introduced in.
• responseObject (class<? extends BaseResponse>) - type of the response object for the command.

@IndentityMapper - parameter level annotation. Used when do search by id, and want both if of the actual DB object and UUID of the object to be accepted as a parameter value.

Fields:

• entityTableName - name of the data base table for the object which id is passed in.

@Parameter - api request parameter level @. Used by Api doc builder as well as by ApiDispatcher (class dispatching the api request and doing basic verification for the parameters)

Fields:

• name (String, empty if not specified) - parameter name. The name should be defined in ApiConstants class as its value is going to be used by the corresponding API response object.
• description (String, empty if not specified) - brief description for the parameter
• required (boolean, false if not specified) - if parameter is required by the command. When required=true and the corresponding parameter is passed in, the command will fail at the dispatch level.
• type (CommandType enum, defaulted to Object if not specified) - parameter type (see CommandType enum below). When passed value's type is different from whatever is defined in the annotation, the command will fail at the dispatch level.
• collectionType (CommandType enum, defaulted to Object if not specified) - if the type of the parameter is instance of List, the collection type has to be defined. The type of all collection elements should be checked against this parameter. Happens at the dispatch level as well.
• expose (boolean, defaulted to true if not specified) - if set to false, 1) the parameter will be ignored even if it's passed to the request 2) Mostly used for the cases when we need an instance variable for the command, but don't want to expose it to the caller.
• includeInApiDoc (boolean, defaulted to true if not specified) - if set to false, won't be included to the API doc.
• length (integer, defaulted to 255 if not specified) - max length for the String parameters.
• since (String, empty if not specified) - mentions the product version the parameter was introduced in.

public enum CommandType

API response annotations">API response annotations

@SerializedName - used by the code for api response serialization and by API doc for defining the API response format.

Fields:

name - the response parameter name.

@Param - used by API doc writer only

Fields:

• description (String, empty if not specified) - brief description for the parameter
• includeInApiDoc (boolean, defaulted to true if not specified) - if set to false, won't be included to the API doc.
• since (String, empty if not specified) - mentions the product version the parameter was introduced in.
• responseObject (defaulted to Object if not specified) - if the response parameter is the response object on its own (like Nic object in the userVmResponse), then the corresponding responseObject should be defined here.

Java to HTML

There is a script that converts the Java annotations to XML output. Then there is a Java program that takes in the xml for the table of contents as well as each command, and generates the required html documents which we upload to our website.

Cosmetic Touch-Ups

1. Check out the code. Be in the right branch.
2. In generatetocforuser.xsl, generatetocfordomainadmin.xsl, generatetocforadmin.xsl, generateadmincommands.xsl, generateusercommands.xsl, and generatedomainadmincommands.xsl, update the software version and any other boilerplate text.
3. Check in your changes to the right branch.

XML to HTML using Jenkins

1. Within a few minutes of checking in your cosmetic changes, you can get the new output. Go to (the build; coming soon!) depending on which branch you want. Under ‘Last Successful Artifacts’ you’ll see the zip file with everything in it.
2. Check the Build History, and make sure that the most recent build succeeded. If it didn’t, you will want to find out why and fix any important problems.
3. Assuming build success, grab that zip file, and unzip it on your machine. Your final unzipped output will be the ~/html folder, which will contain the dynamically generated content, and the static hardcoded files.
4. Upload the HTML to download.cloud.com as described in How to Publish CloudStack Documentation.

Release Notes

There is a "diff.txt" file which is auto-generated. This lists all added, removed, and changed API commands versus the prior point release of CloudStack.