
Settings.xml file
- <resteasy.service.host>http://localhost:8080</resteasy.service.host> This parameter gets used in the maven pom.xml file to compile the Swagger URL. The protocol, host, port if necessary needs to be included in this parameter. Everything to the left of the context URL goes herer.Examples:
- <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