RESTdoc (zero.restdoc.webtools)

The following sections of this article describe using RESTdoc to communicate with your RESTful resources as part of AJAX-driven clients, server-side scripts, and more.

Adding zero.restdoc.webtools to your application

RESTdoc is currently available in the experimental module group.

RESTdoc functionality is added to your application as a dependency. Start by adding the following line to the dependencies element in your config/ivy.xml file:

Run zero resolve to complete the process.

Adding RESTdoc comments to your code

All RESTful resources using the REST conventions of IBM® WebSphere® sMash are indexed and explained using HTML tables. To see the REST API documentation for your application, you must first add RESTdoc comments to each of your RESTful resource methods. RESTdoc comments look exactly like JavaDoc comments, with a few new tags:

@success

Reports the HTTP status code that is returned on success, along with an explanation of what has happened as a result of the operation. An operation can define zero or more success codes, with 200 being the default.

@error

Reports the HTTP error code that is returned when the operation cannot run to completion, along with an explanation of possible causes. An operation can define zero or more errors.

@format

The data format used by an operation to send or receive payloads. For example, the data format of a GET operation refers to the data returned in the response body, while the data format of a POST operation refers to the content that is part of the request body. The value that comes after this tag can be anything, but MIME types such as text/html or application/json are best. These enable users to copy them directly into HTTP request headers.

@example

The value of this tag is free-form. You can use it to show a sample request or response body for the given operation. For example, if you are documenting an onRetrieve() method (HTTP GET) that returns a JSON object, you could provide a sample JSON object that shows all of the fields that can be expected in the response. Your sample data is displayed as-is when a user clicks on the Formats column of the REST table.

The following example shows a proper RESTdoc comment; the syntax is exactly the same whether your code is Java™, Groovy, or PHP:

/**
 *
 * @success 200 Returns the profile for the user with the given ID.
 * @error 403 If the client is not authorized to read the user's profile data.
 * @error 404 If there is no profile for the user with the given ID.
 * @format application/json
 * @example
 * {
 *    "username": "dan", 
 *    "email": "dan@projectzero.org", 
 *    "locale": "en_US"
 * }
 *
 */
def onRetrieve()
{
    // etc.
}

Viewing the REST API documentation

After adding RESTdoc comments to your resource implementations, start your WebSpere sMash application and visit the restdoc resource (by default, http://localhost:8080/resources/restdoc ) in your favorite browser. You should see an index page that lists all of the RESTful resources in your application. Clicking on a name provides the documentation, as the following example shows:

All of the information you put in your RESTdoc comments has been aggregated into an HTML table. Any RESTful methods that were not documented are not included in the table.

Using RESTdoc to explore resources

By default, RESTdoc generates REST tables that link to AJAX-driven test forms. You can click on any value in the URI column of the REST table to see a dialog, as shown in the following example, for setting up and submitting HTTP requests against the resource you are studying:

After you have configured the request data, you can send the request and view all of the response data (headers and body) in the same dialog, as shown in the following example:

This feature is very helpful if you want to reuse RESTful resources and want help writing HTTP client code to communicate with them. The test forms can be used to send and resend requests without switching away from the documentation view, and any changes to the source comments during runtime are reflected in the REST tables the next time they are refreshed.

Generating static documentation

When deploying your WebSphere sMash application in a production environment, you can replace the RESTdoc dynamic table generation with static files (because the APIs are not changing like during development). Run the zero restdoc command; RESTdoc puts the documentation files in /public/docs and their content does not change unless you re-run the command.