In this tutorial, we show you how to develop a simple REST web application with Cuubez API Visualizer.

Prerequisite

  1. cuubez-api-visualizer 1.0.1
  2. JDK 1.6
  3. Tomcat 6.0
  4. Maven 3.0.3
  5. Intellij IDEA 13.1.1

Note If you want to know what and how REST works, just search on Google, ton of available resources.

1. Directory Structure

This is the final web project structure of this tutorial. 
idea project structure 

2. Standard Web Project

Create a standard Maven web project structure.

mvn archetype:generate -DgroupId=com.cuubez -DartifactId=Employee-example
        -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false


Note To support IDEA, use Maven command (Inside project directory):

mvn idea:idea



3. Project Dependencies

The recommended way to get started using cuubez-framework in your project is with a dependency management system – the snippet below can be copied and pasted into your build(pom.xml). Need help? See our getting started guides on building with Maven

File : pom.xml

<dependency>
   <groupId>com.cuubez</groupId>
   <artifactId>cuubez-api-visualizer</artifactId>
   <version>1.0.1</version>
</dependency>

 

4. REST Service

Simple REST service with Cuubez visualization framework annotations. 

EmployeeResource

@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();
    }
 
    @Path("/{empId}")
    @GET
    @Detail("get single employee from the repository")
    @Name("getEmployee")
    @HttpCode("400>No employee found")
    public Response getEmployee(@PathParam("empId") @ParameterDetail("employee identity")final String empId) {
 
        return Response.ok().build();
    }
 
    @Path("/{empId}")
    @DELETE
    @Detail("delete single employee from the repository")
    @Name("deleteEmployee")
    @HttpCode("400>No employee found")
    public Response deleteEmployee(@PathParam("empId") @ParameterDetail("employee identity")final String empId) {
 
        return Response.ok().build();
    }
 
    @Path("/{empId}")
    @PUT
    @Detail("update single employee")
    @Name("updateEmployee")
    @HttpCode("400>No employee found")
    public Response updateEmployee(@PathParam("empId") @ParameterDetail("employee identity")final String empId, Employee employee) {
 
        return Response.ok().build();
    }
}



UserResource

@Path("/users")
@Group(name = "/users", tittle="User resource")
@HttpCode("500>Internal Server Error,200>Success Response")
public class UserResource {
 
    @GET
    @Detail("get all users from the repository")
    @Name("getUsers")
    @ResponseType(User.class)
    public Response getUsers() {
 
        return Response.ok().build();
    }
 
    @POST
    @Detail("add new user to repository")
    @Name("postUser")
    public Response postUser(Employee employee) {
 
        return Response.ok().build();
    }
 
    @Path("/{userId}")
    @GET
    @Detail("get single User from the repository")
    @Name("getUser")
    @HttpCode("400>No user found")
    public Response getUser(@PathParam("userId") @ParameterDetail("user identity")final String userId) {
 
        return Response.ok().build();
    }
 
    @Path("/{userId}")
    @DELETE
    @Detail("delete single User from the repository")
    @Name("deleteUser")
    @HttpCode("400>No user found")
    public Response deleteUser(@PathParam("userId") @ParameterDetail("user identity")final String userId) {
 
        return Response.ok().build();
    }
 
    @Path("/{userId}")
    @PUT
    @Detail("update single User")
    @Name("updateUser")
    @HttpCode("400>No user found")
    public Response updateUser(@PathParam("userId") @ParameterDetail("user identity")final String userId, User employee) {
 
        return Response.ok().build();
    }
}

 

5. web.xml

The VzBootstrapContextListener context listener has to be deployed in order to create the registry for cuubez ,while the VzHttpServletDispatcherservlet is used so that incoming requests are correctly routed to the appropriate services. We have configured the specific servlet, named vapi_servlet, to intercept requests under the /apidoc path. 

File : web.xml

    <listener>
        <listener-class>com.cuubez.visualizer.servlet.VzBootstrapContextListener</listener-class>
    </listener>
 
    <servlet>
        <servlet-name>vapi_servlet</servlet-name>
        <servlet-class>com.cuubez.visualizer.servlet.VzHttpServletDispatcher</servlet-class>
    </servlet>
 
    <servlet-mapping>
        <servlet-name>vapi_servlet</servlet-name>
        <url-pattern>/apidoc</url-pattern>
    </servlet-mapping>

 

6. cuubez-visualize.xml

This configuration file is used to configure API visualizer external user interface

<?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> 

 

7. Demo

URL :- http://localhost:8080/employee-example-1.0.0/apidoc

 

Live Demo >>

 

8. Download

 

Download Project Source Code >>

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.

                         @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 doesn'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>