Auto-generate ReST web services documentation/WADL

Question

We are creating ReST Web Services using ASP.NET and OpenRasta.

Is there any tool that can could help us:

• create WADL file

• or/and create human readable API documentation similar which decribed resources/HTTP methods supported for each resource, etc ?

Answer 1

For OpenRasta, it'd be possible to use a UriDecorator to have help-like URIs defined for your resources (such as /myResource$help). You can then rewrite the URI before parsing to something yo can document easily, parse teh uri, find the resource type, and rewrite to /help/{resourcetype}

From there you register a resource for your help system: ResourceSpace.Has.ResourcesOfType() .AtUri("/help/{resourceType}") .HandledBy() .RenderedByXxx()

Then you can create your handler to return the documentation about a resource. You could for example use the IOperationCreator service to know which http methodds are available and with what input arguments, use the ICodecRepository to see what media types may be accepted as input, and potentially what a media type serialization would look like by calling the codec and generating an html friendly view of it.

That's definitly an area we're going to work on for the next version.

Answer 2

Looks like REST Describe & Compile should do the trick.

On the WADL developer site Marc Hadley maintains a command line tool named WADL2Java. The ambitious goal of REST Describe & Compile is to provide sort of WADL2Anything. So what REST Describe & Compile does is that it:

• Generates new WADL files in a completely interactive way.
• Lets you upload and edit existing WADL files.
• Allows you to compile WADL files to source code in various programming languages.