RESTEasy Swagger Maven Cheat Sheet

dragonFly3

Settings.xml file

  • <deploy.env> This parameter is used for many things that have nothing to do with the RESTful API, but it also plays a role in the RESTful API.  It is used to create the URLs that allow us to access Swagger for the documentation and testing of the API.

In the pom.xml file, in the generate-service-docs execution, the additional parameters docBasePath and apiBasePath rely on both the resteasy.service.host and deploy.env parameters to construct URLs used by Swagger.

RESTeasy entries in web.xml file

https://docs.jboss.org/resteasy/docs/1.0.1.GA/userguide/html/Installation_Configuration.html

<listener>

This entry identifies the RESTeasy class that will initialize RESTeasy.

<listener>
<listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
</listener>

<servlet>

This entry identifies our class that extends the javax.ws.rs.Application class.  The RestApp identifies the RESTful beans, and some other classes that are used in packaging REST responses, formatting JSON, etc.

<servlet>
<servlet-name>Resteasy</servlet-name>
<servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>com.ep.ff.web.endpoint.RestApp</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>

 

<servlet-mapping>
<servlet-name>Resteasy</servlet-name>
<url-pattern>/rest/*</url-pattern>
</servlet-mapping>

<context-param>

Various parameters that control aspects of RESTeasy.  For each the parameter name and value are specified.

<context-param>
<param-name>resteasy.servlet.mapping.prefix</param-name>
<param-value>/rest</param-value>
</context-param>

<context-param>
<param-name>resteasy.jndi.resources</param-name>
<param-value>earname/beanname/local
</param-value>
</context-param>

<context-param>
<param-name>resteasy.role.based.security</param-name>
<param-value>true</param-value>
</context-param>

<security-constraint>

<security-constraint>
<web-resource-collection>
<web-resource-name>REST Resources</web-resource-name>
<url-pattern>/swagger/*</url-pattern>
<url-pattern>/apidocs/*</url-pattern>
<url-pattern>/rest/*</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
<http-method>PUT</http-method>
<http-method>DELETE</http-method>
<http-method>TRACE</http-method>
</web-resource-collection>

<auth-constraint>
<role-name>rolename</role-name>
</auth-constraint>
</security-constraint>

RESTeasy entries in pom files

web

<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jaxrs</artifactId>
<version>3.0.7.Final</version>
</dependency>

<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jackson-provider</artifactId>
<version>3.0.7.Final</version>
</dependency>

web-ejb

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<executions>
<execution>
<id>generate-service-docs</id>
<phase>generate-resources</phase>
<configuration>
<doclet>com.carma.swagger.doclet.ServiceDoclet</doclet>
<docletArtifact>
<groupId>com.carma</groupId>
<artifactId>swagger-doclet</artifactId>
<version>1.0.4.1</version>
</docletArtifact>
<reportOutputDirectory>output directory</reportOutputDirectory>
<useStandardDocletOptions>false</useStandardDocletOptions>
<additionalparam>-apiVersion 1 -docBasePath path/apidocs -apiBasePath path/rest</additionalparam>
</configuration>
<goals>
<goal>javadoc</goal>
</goals>
</execution>
</executions>
</plugin>

The -apiBasePath is used to resolve the URLs to the services for testing the methods via Swagger.  If the {resteasy.service.host} parameter is not supplied, either in the settings.xml file or on the maven command line, you will not be able to click into the links in Swagger to be able to see the documented API or test the services.

Steps to RESTful-ize an existing bean

  • WEB-INF\web.xml needs the web bean added to the resteasy.jndi.resources <context-param> tag in the <param-value> tag.  Follow the same pattern as the existing web beans. Comma delimit.
  • In RestApp.java, add the web bean in the setClasses() method.
  • In the web bean class itself, fix the @EJB annotations to include the name argument.
  • In the web interface class, add class-level and method-level REST annotations.
    • @GET, @POST, @DELETE, @PUT (usually @GET or @POST)
    • @Path(path name).  Take the method name, and change it to be all lower-case, hyphenated, and use that for the path name.
    • @Produces(MediaType.APPLICATION_JSON), @Consumes(MediaType.APPLICATION-JSON)
  • If the method does not have a @RolesAllowed tag, it must be added and tested.  Otherwise anyone will be able to access the method just by knowing the URL.
  • Handle cyclic references with a @JsonIgnore tag, to prevent StackOverflowError.

 

Swagger

Swagger is a tool that helps to document and test a RESTful API.

https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-RESTEasy-2.X-Project-Setup-1.5

Java Classes

RestApp

CustomJacksonJsonProvider

Allows for customization of the methods used to read and write JSON strings.

JsonMappingExceptionMapper

Creates an exception for errors related to Json mapping.

RestResponseInterceptor

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s