kelveden/rastajax

A lightweight library for dynamically generating descriptions of JAX-RS-compliant REST APIs.

Rastajax

A lightweight library for dynamically generating descriptions of JAX-RS-compliant REST APIs. Please see the wiki for an in-depth discussion. The rest of this page is a brief overview and quick start.

Key features

• Standards compliant. Generation of descriptions is based on the annotations from the JAX-RS 1.1 Specification.
• Completely independent of any JAX-RS implementation.
• Lightweight. Dependencies both direct and transitive are kept to a minimum.
• Extensible. Rastajax can be extended with classes that:
  • implement alternative strategies for finding resource classes.
  • use the information scanned in from your resource classes to describe your API in alternative ways.

What's in the box

Rastajax comes as 3 Maven artifacts:

• rastajax-core: The core library. This is the minimum you will need to add to your REST application's classpath.
• rastajax-representation: Contains the default REST API description representations supported by Rastajax. You can extend Rastajax with your own representations either in your own codebase or (even better!) to the rastajax-representation library itself. See the wiki for more details.
• rastajax-servlet: Contains the default servlets that you can use to quickly try out Rastajax. See the "Quick start" section below for more details.

Quick start

Rastajax ships with some default servlets that you can hook in to your REST application to quickly try it out. Here's what you need to do:

1. Add the rastajax-servlet and rastajax-core libraries to your REST application classpath. If you're using Maven as your build tool, this is straightforward enough; add this to your POM:

<dependency>
  <groupId>com.kelveden.rastajax</groupId>
  <artifactId>rastajax-servlet</artifactId>
  <version>0.9.0</version>
  <scope>runtime</scope>
</dependency>

(Maven will pull in rastajax-core as a transitive dependency.)

2. Hook the servlet(s) into your application web.xml:

<context-param>
    <param-name>rastajax.apipackages</param-name>
    <param-value>your.rest.application.package1,your.rest.application.package2</param-value>
</context-param>

...

<servlet>
  <servlet-name>RastajaxHtml</servlet-name>
  <servlet-class>com.kelveden.rastajax.servlet.DefaultHtmlServlet</servlet-class>
</servlet>

<servlet>
  <servlet-name>RastajaxJson</servlet-name>
  <servlet-class>com.kelveden.rastajax.servlet.DefaultJsonServlet</servlet-class>
</servlet>

...

<servlet-mapping>
  <servlet-name>RastajaxHtml</servlet-name>
  <url-pattern>/resources.html</url-pattern>
</servlet-mapping>

<servlet-mapping>
  <servlet-name>RastajaxJson</servlet-name>
  <url-pattern>/resources.json</url-pattern>
</servlet-mapping>

That's it! Now just browse to the servlets and see examples of your API described as JSON and HTML. You can continue using these servlets of course but you'll probably want something more sophisticated longer term. See the wiki for more details on creating how to create your own Rastajax integration.

Logging

Rastasjax logs using the SLF4J logging facade. Why? So that you can continue using your application's existing logging framework without having to worry about managing yet another one.

If your application doesn't already use SLF4J, you'll need to wrap it up as an SLF4J binding using one of the several "bridging" libraries that SLF4J provide. The SLF4J website has extensive notes on doing this. Alternatively, you could switch to a logging framework that exposes itself as a SLF4J binding out of the box - e.g. Logback.

Rastajax info-level logging is pretty minimal; however, if you enable debug-level logging you'll see a load of information explaining exactly how Rastajax processes your application. This is great for diagnostic purposes when Rastajax is processing a resource oddly (or just missing it altogether).

rastajax's Issues

Upload to Maven Central

Provide RepresentationBuilder that can be used in the Swagger UI

AS A consumer of a REST API
I WANT TO be able to browse it using the Swagger UI without the need to concern myself with integrating the REST API with the Swagger back-end.
SO THAT I can take advantage of the rich UI experience provided by the Swagger UI

The architecture for Swagger is split into a server and UI layer. Investigate how realistic it would be to create a RepresentationBuilder that generates JSON in a format that can be consumed by a Swagger UI.

Allow specification of resource filters

AS A developer of a REST API
I WANT TO stop certain resources being represented
SO THAT I can hide resources from the API description that consumers see

This should just be a case of creating a new ResourceFilter interface with a single isResourceAllowedInRepresentation method and make use of it in the ResourceClassLoader. Any number of filters should be allowed to be specified when using the RestDescriber.describeApplication method.

Allow creation of documentation from a combination of templates and Rastajax-generated data

AS a developer of a REST API
I WANT TO be able to generate my documentation from a combination of pre-prepared templates (most likely HTML) and hooks into the rastajax-generated data.
SO THAT I can essentially "embed" the rastajax-generated data in richer, more extensive documentation page(s) than could be produced by creating a simple rastajax servlet.

I'm thinking that the best way to achieve this is to create a rastajax-maven-plugin to process the hooks in the templates. However, a solution that could be re-used by both the Maven plugin and other approaches (for non-Maven folks) would be ideal.

Complete Wiki

Add support for property/field-level JAX-RS annotations

AS A author of a REST API
I WANT TO describe the parameters to my resource methods that are defined as field or property annotations
SO THAT I can view them in the Rastajax description for my API

See Section 3.2 of the JAX-RS API for more information. Note that the objects returned by sub-resource locators should NOT honour these annotations.

Add custom annotations for supplemental descriptions of REST APIs

AS A developer of a REST API
I WANT TO describe my API using annotations provided by Rastajax
SO THAT I can create an explanatory context for the API methods in the representation

Whilst the information provided by the JAX-RS annotations themselves is interesting it doesn't actually describe what each method does in business terms. Therefore, add some annotation(s) to Rastajax to allow further describing of the API.

Off the top of my head a simple @description annotation applicable to resource classes, methods and parameters would suffice. It would then be up to the RepresentationBuilder to use the annotation value as appropriate.