Reference Guide

In real applications creating `new modules to locate communication services would result in a
better organization: For example, using hm-ext-api module for the communication service
interfaces (instead of hm-api as in this example) and hm-ext for the implementations (instead than
hm-bl as in this example).
Creating RSdoc
Trying the REST API with Curl on page 177 describes a way to try the REST API by executing
commands. The HP VAN SDN Controller SDK offers a method to create a semi-automated
interactive RESTful API documentation which offers a better way to interact with REST APIs. It is
called RSdoc because is a combination of JAX-RS [2] and Javadoc [21].
One big advantage of RSdoc is that JAX-RS annotations and Javadoc are already written when
implementing RESTful Web Services, thus in order to enable the application to create the RSdoc is
relatively easy and automatic: a few configuration files need to be updated.
Create a JSON [36] schema to express the data model. Create hm-
rs/src/main/resources/model.json file with the content from the following RSdoc JSON Schema
listing. (To add more schemas, separate them by comma).
RSdoc JSON Schema:
{
"com.hp.hm.model.Switch":
{ "properties":
{
"id": {"type": "long"},
"mac_address": {"type": "string"},
"ip_address": {"type": "string"},
" name": {"type": "string"},
"active_state": {"type": "string"}
}
}
}
Create a class to register the REST API documentation provider under hm-rs module as in the
following DocProvider.java listing. In order to extend from SelfRegisteringRSDocProvider a
dependency must be added. Open the hm-rs/pom.xml file and add the XML extract from the
RSdoc Provider Dependency listing to the <dependencies> node; after updating the POM file
update the Eclipse project dependencies (see Updating Project Dependencies on page 146).
DocProvider.java:
package com.hp.hm.rs;
import org.apache.felix.scr.annotations.Component;
import com.hp.sdn.adm.rsdoc.RSDocProvider;
import com.hp.sdn.adm.rsdoc.SelfRegisteringRSDocProvider;
@Component
public class DocProvider extends SelfRegisteringRSDocProvider {
193