RESTful documentation

You can create RESTful documentation with RESTdoc. All new Project Zero applications include the zero.docs.webtools component that enables the RESTdoc tool while the application is running. The RESTdoc tool generates HTML tables that describe the RESTful APIs exposed by your application and its dependencies. The following sections of this article describe how you can take advantage of RESTdoc to make life easier for programmers who want to communicate with your RESTful resources as part of AJAX-driven clients, server-side scripts, and more.

Adding RESTful comments to your code

All RESTful resources implemented using Project Zero's REST conventions are indexed and explained using HTML tables. To see the RESTful 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 RESTful API documentation

Once you have added RESTdoc comments to your resource implementations, start your Project Zero application and visit http://localhost:8080/resources/docs 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 its 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 left out of 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're studying:



Once 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 for programmers who want to reuse your RESTful resources and need 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.

Configuring RESTdoc output

If RESTdoc is not creating the output you are expecting and you can not find the problem, you can get detailed information on what files it is parsing and what content it finds by setting your logging level to FINE in /config/logging.properties.

When deploying your Project Zero 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). Remove the zero.docs.webtools dependency from your application's Ivy file and run the zero docs command; RESTdoc puts the documentation files in /public/docs and their content does not change unless you re-run the command.