File formats for RADL specification

[jonathanrobie]

We would like to simplify the file formats to make them easier for web clients to read. One idea initially proposed by Satyapal Reddy: extend the OpenAPI format to add missing information. We could do this using Open API vendor extensions. A JSON format is really useful for this kind of machine-readable representation.

We also need to support user-written documentation that might contain tables and other complex formatting, e.g. the documention we provide for authentication. For this, HTML, XML, and Markdown are better choices.

For the final documentation provided to the end user, we will use HTML5.