title: Feature Request for Swift Perfect - RAML
body: <p>As per <a href="http://perfect.org/feature-requests.html" rel="nofollow" title="Perfect Feature Requests">http://perfect.org/feature-requests.html</a></p>
  
  <p>I would like to request that <a href="http://raml.org" rel="nofollow">RAML</a> functionality be included out of the box.</p>
  
  <p>I would like to see something like the following on the server for serving RAML documentation:</p>
  
  <pre><code>server.addRamlDocs(path: "/raml.raml", versionRaml: 1.0, versionApi: "v1", title: "Test API title")
  </code></pre>
  
  <p>This would add a route that when matched creates a full RAML file for all RAML routes.</p>
  
  <p>RAML routes should probably be created in a similar fashion to MustachePageHandler but split into RamlDescriptionHandler, RamlValidateRequestHandler, RamlRequestHandler and RamlResponseHandler.</p>
  
  <p><strong>RamlDescriptionHandler</strong></p>
  
  <p>This should be responsible for:</p>
  
  <ul>
  <li>Describing the request / response</li>
  <li>Automatically creating documentation for the request (when server docs matched)</li>
  </ul>
  
  <p><strong>RamlValidateRequestHandler</strong></p>
  
  <ul>
  <li>Validating and type casting the request</li>
  </ul>
  
  <p>This should then inject HTTPRequest.ramlRequestData and HTTPRequest.ramlRequestIsValid.  This should require no action from the application developer.</p>
  
  <p><strong>RamlRequestHandler</strong></p>
  
  <p>Application logic to be coded by the developer, should check and use HTTPRequest.ramlRequestData and HTTPRequest.ramlRequestIsValid</p>
  
  <p>Should set HTTPResponse.ramlStatus (HTTP Status Code) and HTTPResponse.ramlData </p>
  
  <p><strong>RamlResponseHandler</strong></p>
  
  <p>Should validate the response and send matching against RamlDescriptionHandler, no action from the application developer.</p>