sMash: Sample REST API Documentation

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.