Creating WADL Documentation For REST Endpoints

What is WADL?

Why is it useful?

Annotations

NOTE: This feature is still in active development and annotation definitions are subject to change

WADL documentation can be auto generated for REST Endpoints without any additional effort. However there are some additional annotations that can be used to improve the generated documentation

Component Annotations

All component level annotations are done via cfproperty tags.

Annotation	Description
rest:representation:<format>:<id>	Creates a reference to a global representation. Format can be any mime type file extension (eg: json, html, xml). ID is the name referenced in the request or response

Method Annotations

All method level annotations are done as attributes via cffunctions tags.

Annotation	Description
rest:response:<format>	Specifies the possible response codes and representations for the specified format. This must be supplied in the format: <status>=XXX|element=representation:<id>
rest:queryType	Specifies the type of request media type. Defaults to multipart/form-data for PUT / POST methods and application/x-www-form-urlencoded for all other method types.

Argument Annotations

All argument level annotations are done as attributes via cfarguments tags.

Annotation	Description
rest:options	Enumerates the possible options for the argument using a | pipe delimited list. This can be a simple list or name value pairs. ( http://www.w3.org/Submission/wadl/#x3-280002.12.3)
rest:type	An optional attribute whose type is a space-separated list of of xsd:anyURI. Default to xsd:XXX where XXX is the value of the type attribute of the argument tag. ( http://www.w3.org/Submission/wadl/#x3-120002.6)

Here is an example:

!#xml
<cfcomponent
	displayname="ContentServiceEndpoint"
	extends="MachII.endpoints.rest.BaseEndpoint"
	output="false"
	hint="RESTful endpoint for the Content Service.">

	<cfproperty name="rest:representation:json:contentItem" value="http://www.example.com/entities/contentItem">

	<cffunction name="getContentItem" access="public" returntype="String" output="false"
				hint="Retrieves an individual content item."
				rest:uri="/content/item/{key}"
				rest:method="GET"
				rest:response:html="status=200,status=404"
				rest:response:json="status=200|element=representation:contentItem">

		<cfargument name="key" type="string" required="true" >
		<cfargument name="format" type="string" required="false" default="html"
					hint="Determines the response to be provided"
					rest:options="html=application/xml|json=application/json|teaser=application/xml"
					/>
		<cfargument name="version" type="string" required="false" default="approved"
					hint="Set the version to retrieve a specific version of this content item."
					rest:options="approved|latest" />
		<cfargument name="locale" type="string" required="false" default="en_US"
					hint="The locale of the item being requested"
					/>
        </cffunction>
</cfcomponent>