Over a million developers have joined DZone.

Jersey REST Web Service API Documentation

Visually compose APIs with easy-to-use tooling. Learn how IBM API Connect provides near-universal access to data and services both on-premises and in the cloud, brought to you in partnership with IBM.

In this tutorial, we show you how to develop a simple REST web application with Jersey framework and visualize API's using Cuubez API Visualizer.

Prerequisite

  1. jersey-server 1.9
  2. cuubez-api-visualizer 1.0.1
  3. JDK 1.6
  4. Tomcat 6.0
  5. Maven 3.0.3
  6. 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. 


2. Standard Web Project 

 Create a standard Maven web project structure.
mvn archetype:generate -DgroupId=com.jersey -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 Jersey framework and cuubez-api-visualizer 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
<dependency>
    <groupId>com.sun.jersey</groupId>
    <artifactId>jersey-server</artifactId>
    <version>1.9</version>
</dependency>

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

4. REST Service

 Simple REST service with Jersey and  Cuubez visualization frameworks annotations. 

EmployeeResource

@Path("/employees")
@Group(name = "/employee", title="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, @M @ParameterDetail("Organization id")@HeaderParam("org_id")String ogrId) {

        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(Employee employee) {

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


}

UserResource

@Path("/users")
@Group(name = "/users", title="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(User user) {

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

}

5. web.xml

Jersey configurations.
ServletContainer is used so that incoming requests are correctly routed to the appropriate Jersey services. We have configured the specific servlet, named jersey-serlvet, to intercept requests under the /rest/* path. 
Cuubez API Visualizer configurations.
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
<display-name>Employee Example</display-name>

    <!--jersey configurations -->

    <servlet>
        <servlet-name>jersey-serlvet</servlet-name>
        <servlet-class>
            com.sun.jersey.spi.container.servlet.ServletContainer
        </servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>jersey-serlvet</servlet-name>
        <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>

     <!-- Cuubez API Visualizer configurations -->
    <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>Jersey Sample API Documentation</header>
        <title>Jersey Sample API Documentation</title>
        <logo-include>true</logo-include>
        <logo-url>https://jersey.java.net/images/jersey_logo.png</logo-url>
        <description>
            <header>Jersey Sample API Description</header>
            <detail>(Jersey sample description)Use virtual networking services among devices that are managed by the OpenStack Compute service. The Networking (neutron) API v2.0 combines the API v1.1 functionality with some essential Internet Protocol Address Management (IPAM) functionality.</detail>
        </description>
    </display>
</Configuration>

7. Demo

Visually compose APIs with easy-to-use tooling. Learn how IBM API Connect provides near-universal access to data and services both on-premises and in the cloud, brought to you in partnership with IBM.

Topics:

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}