respect-rails 0.1.0

data/FAQ.md

@@ -0,0 +1,98 @@
+# Frequently Asked Question
+
+## Why using Respect for Rails since I do most of my parameters checking in my model?
+
+This is true that complex parameters ckecking/conversions are often done in the model in
+order to factor code when multiple endpoints use them. For instance, consider the following
+case where the user must provide a circle, via a center point and a radius:
+
+```ruby
+class Hotspot < ActiveRecord::Base
+  # Returns the list of hot-spots around the given circle.
+  #
+  # The following statements are equivalent:
+  #   Hotspot.around(Circle.new(Point.new(42, 51), 16))
+  #   Hotspot.around(center: { x: 42, y: 51 }, radius: 16)
+  def self.around(*args)
+    if args.is_a? Hash
+      # Build a circle from the hash parameters and call this
+      # method recursively.
+      self.around(Circle.from_h(args.first))
+    else
+      circle = args.shift
+      # Do the query.
+    end
+  end
+end
+
+class HotspotController < ActionController::Base
+  def around
+    Hotspot.around(params[:area])
+  end
+end
+```
+
+In this case all the sanitization process is handled by the `Circle::from_h` method.  This code
+is ok.  However, it has some drawbacks:
+
+1. We still have to write the documentation for the REST API and it would be hard to imagine
+   a generator that could understand this code or complex `ActiveRecord` validator code.
+1. Although the `Circle::from_h` method may be already provided by a basic third-party library,
+   it may not do all the checking necessary when user data come from an HTTP request.
+   For instance, it may not handle properly a call like this one:
+     `Circle.from_h(center: { x: "foo", y: "bar" }, radius: "invalid")`
+1. In case of invalid schema the user may not get an helpful message.  This is perfectly
+   acceptable for security reason.
+
+We can get _Respect for Rails_ do this work for you by adding a helper method which create a
+`Circle` object for you when validating the JSON document:
+
+```ruby
+module Respect
+  class PointSchema < CompositeSchema
+    def schema_definition
+      HashSchema.define do |s|
+        s.numeric "x"
+        s.numeric "y"
+      end
+    end
+
+    def sanitize(doc)
+      Point.new(doc["x"], doc["y"])
+    end
+  end
+
+  class CircleSchema < CompositeSchema
+    def schema
+      HashSchema.define do |s|
+        s.point "center"
+        s.numeric "radius", greater_than: 0
+      end
+    end
+
+    def sanitize(doc)
+      Circle.new(doc[:center], doc[:radius])
+    end
+  end
+end
+```
+
+and have your schema written like this
+
+```ruby
+class HotspotSchema < Respect::Rails::ActionSchema
+  def around
+    request do
+      schema do |s|
+        s.circle "area"
+      end
+    end
+  end
+end
+```
+
+_Respect for Rails_ does not aim at replacing `ActiveRecord` validator. In other word, some
+parameters may be validated by _Respect_ and still generate an `ActiveRecord` error. It is here
+to prepare the data for the model, to prevent security issues and to provide a place for
+documenting each parameter. See it as a full featured alternative to
+[Strong Parameters](https://github.com/rails/strong_parameters).

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,291 @@
+# Respect plugin for Rails
+
+_Respect for Rails_ let's you write the documentation of your REST API using Ruby code. Your app's
+API is published using a Rails engine so it is always deployed along with your application and stay
+synchronized. A filter is available so you can also easily validate requests and responses. Thanks
+to that your incoming parameters will also be sanitized so if you expect a URI in a parameter value you will get a URI object instead of a string object containing a URI.
+It follows Rails DRY principle and save you a lot of typing since it
+fetches most of the information automatically by inspecting your routes, their constraints and your
+model validators. You can always adjust the default by defining the schema per resource and/or
+controller.
+
+# Features
+
+* A compact DSL from to the [Respect](https://github.com/nicolasdespres/respect) gem to specify your REST API documentation.
+* Filters to automatically validates and sanitize incoming parameters.
+* A Rails engine to serve your public REST API documentation.
+
+See the RELEASE_NOTES file for detailed feature listing.
+
+# Take a tour
+
+This section guides for a walk around the main features available.
+
+## Document an action request
+
+_Respect for Rails_ let's you easily describe the structure of incoming requests and outgoing responses
+using a simple and compact Ruby DSL. Assuming you have the scaffold of a `ContactsController`, the structure
+for its `create` action may look like this:
+
+```ruby
+# in app/controllers/contacts_controller_schema.rb
+# POST /contacts
+# POST /contacts.json
+def_action_schema :create do |a|
+  a.documentation "Create a new contact in the address book."
+  a.request do |r|
+    r.body_parameters do |s|
+      # They look like something like that:
+      #   { contact: { name: "Albert", age: 62, homepage: "http://example.org" } }
+      s.hash "contact" do |s|
+        s.string "name", doc: "The name of the contact."
+        s.integer "age", doc: "How old is the contact."
+        s.uri "homepage", doc: "The URL of the contact's homepage"
+      end
+    end
+  end
+end
+def create
+  # ...
+end
+```
+
+Note that we distinguish from where the parameters comes from (path, query or body) for the sake of documentation.
+To see the generated doc, you must mount the provided engine like this:
+
+```ruby
+# in config/routes.rb
+mount Respect::Rails::Engine => "/rest_spec"
+```
+
+and point your favorite web browser to `http://localhost:3000/rest_spec`. You should see something like that
+
+![Alt Text](examples/screenshots/controllers_create_request.png "A request documentation")
+
+## Document an action response
+
+When documenting an API it is also important to write how the response will look like. You can add this code
+to specify the body of the response when the status is "created":
+
+```ruby
+# in app/controllers/contacts_controller_schema.rb
+# in def_action_schema :create block
+a.response_for do |status|
+  status.created do |r|
+    r.body do |s|
+      s.integer name, greather_than: 0, doc: "The identifier of this contact."
+      s.string "name", doc: "The name of the contact."
+      s.integer "age", doc: "How old is the contact."
+      s.uri "homepage", doc: "The URL of the contact's homepage"
+      s.datetime "created_at", doc: "When this record has been created."
+      s.datetime "updated_at", doc: "When this record has been updated lastly."
+    end
+  end
+end
+```
+
+The generated documentation would look like that:
+
+![Alt Text](examples/screenshots/controllers_create_response.png "A response documentation")
+
+The specification standard used to document schema is defined at [json-schema.org](http://json-schema.org/)
+(we currenly follow [draft v3](http://tools.ietf.org/id/draft-zyp-json-schema-03.html)).
+
+## Factor specification code
+
+As you have probably noticed there is some repetition in this code. To avoid it you can create an helper
+like this:
+
+```ruby
+# in app/helpers/respect/application_macros.rb
+module Respect
+  module ApplicationMacros
+    def id(name = "id")
+      integer name, greather_than: 0
+    end
+
+    def contact_attributes
+      string "name", doc: "The name of the contact."
+      integer "age", doc: "How old is the contact."
+      uri "homepage", doc: "The URL of the contact's homepage"
+    end
+
+    def contact
+      id
+      contact_attributes
+      record_timestamps
+    end
+
+    def record_timestamps
+      doc "When this record has been created."
+      datetime "created_at"
+      doc "When this record has been updated lastly."
+      datetime "updated_at"
+    end
+  end
+end
+```
+
+Notice that we have also provided a macro for the usual +id+ attribute. This helper must be install in the
+schema definition DSL like that:
+
+```ruby
+# in config/initializers/respect.rb
+Respect::Rails.setup do |config|
+  config.helpers Respect::ApplicationMacros
+end
+```
+
+Now the request schema can be rewritten like this:
+
+```ruby
+r.body_parameters do |s|
+  s.hash "contact" do |s|
+    s.contact_attributes
+  end
+end
+```
+
+and the response schema like that:
+
+```ruby
+r.body do |s|
+  s.hash "contact" do |s|
+    s.contact
+  end
+end
+```
+
+## Validate requests and response
+
+All the information you have included in the action specification can also be used to drive a
+validation process. To enable it you just have to install an "around" filter in your
+`ApplicationController` like this:
+
+```ruby
+around_filter :validate_schemas!
+```
+
+Responses formatted in JSON are validated only in development and test mode.
+When validation failed an exception is raised. To help you debug, we provide a more specific
+view than the usual exception reporting view of Rails. You can install this view by adding the
+following line to your `ApplicationController`:
+
+```ruby
+rescue_from_request_validation_error if Rails.env.development?
+```
+
+## Sanitize your incoming parameters
+
+Incoming requests parameters must often be sanitized since they come from un-trusted users.
+A sanitized version of the request parameters is built along the validation process and stored
+in the `request` object. We can access it using `request.sane_params`. Sanitized object of a
+more specific type than the original parameter value. For instance the `homepage` parameter
+will be a `URI` object instead of a simple string:
+
+```ruby
+request.sane_params[:contact][:homepage].class  #=> URI::Generic
+```
+
+You can also automatically sanitize the request parameters *in-place* by installing this before
+filter:
+
+``` ruby
+before_filter :sanitize_params!
+```
+
+## Headers documentation
+
+Often REST API expect headers to be set in the request and/or set headers in their responses.
+_Respect for Rails_ let's you document using the `headers` command available for both
+the request and the response.
+
+```ruby
+a.request do |r|
+  r.headers do |h|
+    h.doc "Set this header."
+    h['X-AB-Signature'] = "api_public_key"
+  end
+end
+```
+
+## Documentation string
+
+The DSL let you write documentation string at many places. All this string are structured with a title
+on the first line followed by an empty line and a description for the rest of the string. It is much
+like git commit message except that if there is only one paragraph the title will be omit. You can set
+the documentation like this of most of the item using the `doc` statement or the `:doc` option when
+available. See this example:
+
+```ruby
+doc <<-EOS.strip_heredoc
+  The name of the contact.
+
+  First name and last name are separated by white space.
+  EOS
+string "name"
+
+doc "How old is the contact."
+integer "age"
+
+uri "homepage", doc: "The URL of the contact's homepage"
+```
+
+# Getting started
+
+The easiest way to install _Respect for Rails_ is to add it to your `Gemfile`:
+
+```ruby
+gem "respect-rails", require: "respect/rails"
+```
+
+Then, after running the `bundle install` command, you can mount the Rails engine provided by this library
+by adding this line at the beginning of your `config/routes.rb` file.
+
+```ruby
+mount Respect::Rails::Engine => "/rest_spec"
+```
+
+Then, you can start your application web server as usual at point your web browser to
+`http://localhost:3000/rest_spec/doc`.
+
+# Getting help
+
+The easiest way to get help about how to use this library is to post your question on the
+[Respect for Rails discussion group](https://groups.google.com/forum/#!forum/ruby-respect-gem-talk).
+I will be glade to answer. I may have already answered the
+same question so before, you post your question take a bit of time to search the group.
+
+You can also read these documents for further documentation:
+
+* [Respect project](https://github.com/nicolasdespres/respect)
+* [Repect API reference documentation](http://nicolasdespres.github.io/respect/)
+* [Repect for Rails API reference documentation](http://nicolasdespres.github.io/respect-rails)
+* The FAQ file.
+
+# Compatibility
+
+_Respect for Rails_ has been tested with:
+
+* Ruby 1.9.3-p392 (should be compatible with all 1.9.x family)
+* Rails 3.2.13
+* Respect 0.1.0
+
+Note that it uses `ActiveSupport::JSON` to encode/decode JSON objects.
+
+# Feedback
+
+I would love to hear what you think about this library. Feel free to post any comments/remarks on the
+[Respect for Rails discussion group](https://groups.google.com/forum/#!forum/ruby-respect-gem-talk).
+
+# Contributing patches
+
+I spent quite a lot of time writing this gem but there is still a lot of work to do. Whether it
+is a bug-fix, a new feature, some code re-factoring, or documentation clarification, I will be
+glade to merge your pull request on GitHub. You just have to create a branch from `master` and
+send me a pull request.
+
+# License
+
+_Respect for Rails_ is released under the term of the [MIT License](http://opensource.org/licenses/MIT).
+Copyright (c) 2013 Nicolas Despres.

data/RELATED_WORK.md

@@ -0,0 +1,47 @@
+# Related works
+
+This section describes some projects sharing more or less the same purpose as
+_Respect for Rails_. The goal is to have an overview of the eco-system around this
+topic to borrow ideas and to drive implementation.
+
+This section is not meant to be accurate even if we try to stay objective here.
+
+## [apipie-rails](https://github.com/Pajk/apipie-rails)
+
+* Documentation generation using an engine.
+* Ruby DSL to describe documentation.
+* Support validators.
+* Resource and controllers description API.
+* Good looking generated doc.
+* Allow to statically deployed the documentation apart of the Rails app.
+* Apparently there is no sanitizer.
+* Apparently you can't specify headers.
+* Apparently you can't specify url and query parameters.
+* Apparently there is no support for json-schema.org standard.
+
+TODO: Study to be continued...
+
+## [Doctorj](https://github.com/coopernurse/doctorj)
+
+* No Ruby DSL but uses a Markdown file as input.
+  * Syntax to describe schema in Markdown looks compact and close to what we have
+    in our Ruby DSL.
+* Generate API documentation in HTML.
+* Not integrated in Rails.
+  * Not bind to the routes.
+  * No HTTP headers validation possible.
+* No sanitizer.
+
+## [Rails::API](https://github.com/rails-api/rails-api)
+
+* Lighter Rails for JSON only application.
+
+## [Active Model Serializer](https://github.com/rails-api/active_model_serializers)
+
+* Object oriented way to organize JSON view code.
+
+## [StrongParameters](https://github.com/rails/strong_parameters)
+
+* No documentation generation.
+* No sanitizer.
+* No response validation.

data/RELEASE_NOTES.md

@@ -0,0 +1,20 @@
+# Release notes
+
+This document is a list of user visible feature changes made between
+releases except for bug fixes.
+
+Note that each entry is kept so brief that no reason behind or
+reference information is supplied with.  For a full list of changes
+with all sufficient information, see the git(1) log.
+
+A lot more is coming soon check out the issue tagged as `feature`
+in the tracker.
+
+## Part of the first release
+
+* Feature: An engine to render and deploy the REST API documentation.
+* Feature: Filter to validate requests/responses.
+* Feature: Sanitizer to promote validated parameter value to a more precise type.
+* Feature: Schema are organize like controllers and views.
+* Feature: Follow [JSON schema draft v3 standard](http://tools.ietf.org/id/draft-zyp-json-schema-03.html) to represents schema.
+* Feature: A RequestValidationError exception handler.

data/Rakefile

@@ -0,0 +1,32 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files = [
+    'lib/**/*.rb',
+    '-',
+    'README.md',
+    'FAQ.md',
+    'RELEASE_NOTES.md',
+    'RELATED_WORK.md',
+  ]
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/assets/javascripts/respect/rails/schemas.js

@@ -0,0 +1,32 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .
+
+var toggle = function(id) {
+  var s = document.getElementById("toggle_" + id).style;
+  var t = document.getElementById("toggle_" + id + "_toggle");
+  if (s.display == 'none') {
+    s.display = 'block';
+    t.innerHTML = t.innerHTML.replace(/^Show/, 'Hide');
+  } else {
+    s.display = 'none';
+    t.innerHTML = t.innerHTML.replace(/^Hide/, 'Show');
+  }
+  return false;
+}
+
+var toggleHeadersDump = function() {
+  return toggle('headers_dump');
+}

data/app/assets/stylesheets/respect/rails/schemas.css

@@ -0,0 +1,160 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */
+
+body { background-color: #fff; color: #333; }
+
+body, p, ol, ul, td {
+  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-size:   14px;
+  line-height: 1.4;
+}
+
+body {
+  padding-top: 20px;
+  padding-bottom: 40px;
+  width: 1024px;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+pre {
+  background-color: #f8f8f8;
+  padding: 10px;
+  font-family: monospace;
+  font-size: 13px;
+  white-space: pre;
+  border-style: solid;
+  border-width: 1px;
+  border-color: #ccc;
+}
+
+a {
+  color: rgb(205, 91, 69);
+  text-decoration: none;
+}
+a:hover {
+  color: rgb(205, 91, 69);
+  text-decoration: underline;
+}
+
+h1 {
+  font-size: 30px;
+}
+
+h2 {
+  font-size: 27px;
+}
+
+h3 {
+  font-size: 22px;
+}
+
+hr {
+  border-color: rgb(205, 91, 69);
+  border-width: 4px;
+  border-style: solid;
+  margin-top: 50px;
+  margin-bottom: 50px;
+}
+
+table {
+  width: 100%;
+  border-spacing: 0px;
+  border-collapse: collapse;
+}
+
+tr:hover {
+  background-color: rgb(255, 240, 237);
+}
+
+td {
+  padding-top: 6px;
+  padding-bottom: 6px;
+  padding-left: 8px;
+  border-top-style: solid;
+  border-top-width: 1px;
+  border-top-color: #ccc;
+  border-bottom-style: solid;
+  border-bottom-width: 1px;
+  border-bottom-color: #ccc;
+  text-align: left;
+}
+
+.summary {
+  padding-top: 15px;
+  padding-left: 15px;
+  display: block;
+}
+
+
+/* Table of contents */
+
+.toc .title {
+  border-bottom-width: 1px;
+  border-bottom-style: solid;
+  border-bottom-color: rgb(205, 91, 69);
+  line-height: 30px;
+  margin-bottom: 40px;
+}
+
+.toc h3 {
+  color: rgb(205, 91, 69);
+}
+
+/* Route section */
+
+.route .title a:hover {
+  text-decoration: none;
+}
+
+.route td {
+  vertical-align: top;
+}
+
+.route ul {
+  padding-left: 20px;
+  margin-top: 0;
+  margin-bottom: 0;
+}
+
+.route li {
+  /* list-style-type: none; */
+}
+
+.route .constraint {
+  color: rgb(100, 100, 100);
+  font-size: smaller;
+}
+
+/* JSON highlighting */
+
+.json_highlight .keyword {
+  font-weight: bold;
+}
+
+.json_highlight .numeric {
+  color: #099;
+}
+
+.json_highlight .key {
+  color: #000080;
+}
+
+.json_highlight .string {
+  color: #d14;
+}
+
+.json_highlight .comment {
+  color: rgb(236, 166, 18);
+}