Documentation
Cuubez API Visualizer is 100% java based open source software which is published under the Apache 2.0 license. It provides very easy, quick and attractive solution for the RESTful web service’s API document visualizing. This API visualizing framework supports all JAXRS based java REST frameworks and none JAXRS java based REST frameworks that are currently available in the industry.

1 Configuration

Cuubez API visualizer can be used very easily with Java based REST frameworks without any complex configurations. These configurations can be categorized in to three major sections.
  1. Annotation based configuration
  2. XML based configurations.
  3. Display configuration

Both Annotation based and XML based configurations are basically used to setup RESTful web service resources while Display configuration is used to configure external user interface elements. Annotation based configurations are developed using few of the framework specific annotations and JAXRS based standard annotations, beside XML based and Display based configurations are using separate set of specific XML elements. Only one configuration type can be used at a time and that configuration can be done via web.xml context parameters.
Note:- Default configuration type is set to annotation based.

web.xml
<context-param>
	<param-name>configuration-type</param-name>
        <param-value>xml-configuration</param-value>
</context-param>
Note:- Configuration values could be xml-configuration or annotation-configuration

1.1 Annotation based configurations

nnotation based configuration using standard JAXRS based annotations and custom framework based annotations.
Following are the framework specific annotations.
  • @Group Annotation
  • Properties
    name = group name.
    tittle = group tittle.
    This annotation is a class level annotation and use to group set of resources.
    @Group(name=”/user” tittle=”User Resource”)

  • @HttpCode Annotation
  • Properties
    value = Http code and reason. Http code and reason details separate from “>” symbol. This can contain more than one Http code separation from the “,” symbol.
    This annotation is class level annotation.
    Eg:- @HttpCode(“500>Internal Server Error,200>Success Response,404>Resource Not Found”)

  • @Name Annotation
  • Properties
    value = Name of the REST resource.
    This is method level annotation.
    @Name(“Create Employee")

  • @Detail Annotation
  • Properties
    value = Detail of the REST resource.
    @Detail(“Add new employee to repository”)

  • @ResponseType Annotation
  • Properties
    value = Response type of the REST resource.
    This is method level annotation.
    @ResponseType(User.class)

  • @ParameterDetail Annotation
  • Properties
    value = Detail of the parameter.
    This is parameter level annotation.
    @ParameterDetail(“Employee Identity”)

  • @M Annotation
  • Properties
    This annotation dosen’t has any properties.
    This annotation is parameter level annotation and use to mark parameter as a mandatory parameter.

@Path("/employees")
@Group(name = "/employee", tittle="Employee resource")
@HttpCode("500>Internal Server Error,200>Success Response")
public class EmployeeResource {


    @GET
    @Detail("get all employee from the repository")
    @Name("getEmployees")
    @ResponseType(Employee.class)
    public Response getEmployees() {

        return Response.ok().build();
    }

    @POST
    @Detail("add new employee to repository")
    @Name("postEmployee")
    public Response postEmployee(Employee employee) {

        return Response.ok().build();
    }
}


1.2 XML based configurations

XML configuration using a specific set of annotations and a specific file are used to configure these. This file name should be “cuubez-visualize.xml “and could be locatedvon any location in the project. The same file is used to configure both XML based and Display based configurations.

1.2.1 Display configuration elements

Display configuration is used to configure external look and field of the API visualizer. Separate XML(“cuubez-visualize.xml”) file is using to configure following configuration elements.

<display> Root element of the display configuration.
  <title> Html title value
  <header> API Visualizer main header
  <logo-include> This element can be use to enable or disable logo of the visualizer.
  <logo-url> Logo URL
  <description> Root element of the API visualizer description.
   <header> Header of the description
   <detail> Detail of the description


<?xml version="1.0"?>
<Configuration>
    <display>
        <header>Cuubez API Documentation</header>
        <tittle>Cuubez API Documentation</tittle>
        <logo-include>true</logo-include>
        <logo-url>https://code.google.com/p/cuubez/logo?cct=1409036089</logo-url>
        <description>
            <header>Cuubez Sample API Description</header>
            <detail>Would you like to document your API with style? Cuubez API Visualizer is a complete framework implementation for 
            the API documentation. It provide annotation based solution for the JaxRS web services frameworks and XML configuration based solution for the any java RESTful frameworks. Simplicity is the major strength of the API visualizer.</detail>
        </description>
    </display>
</Configuration> 


1.2.2 Resource configuration elements

Resource configuration is used to configure resources which are needed to represent via API visualizer. It uses the same configuration file which is used to configure display configuration.

<groups> This element is use to group set of resource groups
  <group> This is root element of the group
   <name> Group name
   <title> Group title
   <http-codes> This include set of common http codes for the group
    <http-code> Root element of the http code
    <code> Http code
    <reason> Reason for the http code
   <resources> This element use for grouping set of resources
    <resource> Root element of the resource
    <http-codes> This element is use to group resource level http codes
     <http-code> Root element of the http code
      <code> Http code
       <reason> Reason for the http code
     <path> Resource path
     <name> Resource name
     <http-method> Http method (GET, POST, PUT, DELETE, OPTION, HEAD)
     <detail> Detail of the resource
     <request-body-type> Request body type of the resource
     <response-body-type> Response body type of the resource
     <variables> This element is use to group set of resource variables
      <variable> Root element of the resource variable
       <name> Variable name
       <parameter-type> Parameter type (Query, Path,Header)
       <variable-type> variable type (String, int..)
       <description> Description of the variable
       <mandatory> This element can set variable as a mandatory or optional value could be true or false


    <groups>
        <group>
            <name>/network</name>
            <title>asdas</title>
            <http-codes>
                <http-code>
                    <code>500</code>
                    <reason>Internal Server Error</reason>
                </http-code>
            </http-codes>
            <resources>
                <resource>
                    <http-codes>
                        <http-code>
                            <code>404</code>
                            <reason>Page Not Found</reason>
                        </http-code>
                    </http-codes>
                    <path>/networks/{network_id}</path>
                    <name>Network get API</name>
                    <http-method>GET</http-method>
                    <detail>details about the network API</detail>
                    <request-body-type>com.fe.User</request-body-type>
                    <response-body-type></response-body-type>
                    <variables>
                        <variable>
                            <name>network id</name>
                            <variable-type>String</variable-type>
                            <parameter-type>path</parameter-type>
                            <description>network id</description>
                            <mandatory>true</mandatory>
                        </variable>
                        <variable>
                            <name>name</name>
                            <variable-type>String</variable-type>
                            <parameter-type>query</parameter-type>
                            <description>network name</description>
                            <mandatory>false</mandatory>
                        </variable>
                    </variables>
                </resource>
          </resources>
     </group>
</groups>