Quick Start

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