DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations
Securing Your Software Supply Chain with JFrog and Azure
Register Today

Trending

  • Microservices With Apache Camel and Quarkus (Part 2)
  • Health Check Response Format for HTTP APIs
  • Step Into Serverless Computing
  • Microservices With Apache Camel and Quarkus (Part 3)

Trending

  • Microservices With Apache Camel and Quarkus (Part 2)
  • Health Check Response Format for HTTP APIs
  • Step Into Serverless Computing
  • Microservices With Apache Camel and Quarkus (Part 3)
  1. DZone
  2. Software Design and Architecture
  3. Integration
  4. Jersey REST Web Service API Documentation

Jersey REST Web Service API Documentation

Prabath  Ariyarathna user avatar by
Prabath Ariyarathna
·
Oct. 08, 14 · Interview
Like (1)
Save
Tweet
Share
9.72K Views

Join the DZone community and get the full member experience.

Join For Free

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

WADL File
http://localhost:8080/employee-example-1.0.0/rest/application.wadl


API Visualizer

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


8. Download

employee-example-jersey.zip 
API REST Web Protocols Web Service Documentation

Opinions expressed by DZone contributors are their own.

Trending

  • Microservices With Apache Camel and Quarkus (Part 2)
  • Health Check Response Format for HTTP APIs
  • Step Into Serverless Computing
  • Microservices With Apache Camel and Quarkus (Part 3)

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com

Let's be friends: