RESTEasy Swagger Maven Cheat Sheet


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 and deploy.env parameters to construct URLs used by Swagger.

RESTeasy entries in web.xml file


This entry identifies the RESTeasy class that will initialize RESTeasy.



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






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





<web-resource-name>REST Resources</web-resource-name>


RESTeasy entries in pom files





<reportOutputDirectory>output directory</reportOutputDirectory>
<additionalparam>-apiVersion 1 -docBasePath path/apidocs -apiBasePath path/rest</additionalparam>

The -apiBasePath is used to resolve the URLs to the services for testing the methods via Swagger.  If the {} 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, 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 is a tool that helps to document and test a RESTful API.

Java Classes



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


Creates an exception for errors related to Json mapping.


Leave a Reply

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

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

Google photo

You are commenting using your Google 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 )

Connecting to %s