Creating WADL Documentation For REST Endpoints - Mach-II/Mach-II-Framework GitHub Wiki
NOTE: This feature is still in active development and annotation definitions are subject to change
TODO
TODO
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
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 |
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 |
| 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. |
All argument level annotations are done as attributes via cfarguments tags.
| Annotation | Description |
|---|---|
| rest:options | Enumerates the possible options for the argument using a ` |
| 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:
<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>