Jersey REST Web Service API Documentation
DZone's Guide to
Jersey REST Web Service API Documentation
Join the DZone community and get the full member experience.
Join For FreeWSO2 is the only open source vendor to be named a leader in The Forrester Wave™: API Management Solutions, Q4 2018 Report. Download the report now or try out our product 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
- jersey-server 1.9
- cuubez-api-visualizer 1.0.1
- JDK 1.6
- Tomcat 6.0
- Maven 3.0.3
- 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.
4. REST Service
Jersey configurations.
6. cuubez-visualize.xml
<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
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
IAM is now more than a security project. It’s an enabler for an integration agile enterprise. If you’re currently evaluating an identity solution or exploring IAM, join this webinar.
Like This Article? Read More From DZone
Topics:
Opinions expressed by DZone contributors are their own.
{{ parent.title || parent.header.title}}
{{ parent.tldr }}
{{ parent.linkDescription }}
{{ parent.urlSource.name }}