interpol 0.0.2 → 0.0.3

data/Gemfile

@@ -8,3 +8,4 @@ group :extras do
 end
 
 gem 'json-jruby', platform: 'jruby'
+gem 'compass_twitter_bootstrap', git: 'git://github.com/vwall/compass-twitter-bootstrap.git'

data/README.md

@@ -19,8 +19,8 @@ definitions:
   validates your API responses against the JSON schema in your endpoint
   definition files. This is useful in test/development environments to
   ensure that your real API returns valid responses.
-* A documentation browser for your API is planned as well (but not yet
-  implemented).
+* `Interpol::DocumentationApp` builds a sinatra app that renders
+  documentation for your API based on the endpoint definitions.
 
 You can use any of these tools individually or some combination of all
 of them.
@@ -81,7 +81,8 @@ definitions:
 Let's look at this YAML file, point-by-point:
 
 * `name` can be anything you want. Each endpoint should have a different name. Interpol uses
-  it in schema validation error messages.
+  it in schema validation error messages. It is also used by the
+  documentation app.
 * `route` defines the sinatra route for this endpoint. Note that while
   Interpol::StubApp supports any sinatra route, Interpol::ResponseSchemaValidator
   (which has to find a matching endpoint definition from the request path), only
@@ -159,6 +160,12 @@ Interpol.default_configuration do |config|
   #
   # Used by Interpol::ResponseSchemaValidator.
   config.validation_mode = :error # or :warn
+
+  # Determines the title shown on the rendered documentation
+  # pages.
+  #
+  # Used by Interpol::DocumentationApp.
+  config.documentation_title = "Acme Widget API Documentaton"
 end
 
 ```
@@ -254,6 +261,29 @@ get '/users/:user_id/projects' do
 end
 ```
 
+### Interpol::DocumentationApp
+
+This will build a little sinatra app that renders documentation
+about your API based on your endpoint definitions.
+
+``` ruby
+# config.ru
+
+require 'interpol/documentation_app'
+
+# the block is only necessary if you want to override the default
+# config or if you have not set a default config.
+doc_app = Interpol::DocumentationApp.build do |app|
+  app.endpoint_definition_files = Dir["config/endpoints_definitions/*.yml"]
+  app.documentation_title = "My API Documentation"
+end
+
+run doc_app
+```
+
+Note: the documentation app is definitely a work-in-progress and I'm not
+a front-end/UI developer. I'd happily accept a pull request improving it!
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -21,3 +21,25 @@ else
 end
 
 task default: [:spec, :quality]
+
+desc "Watch Documentation App Compass Files"
+task :compass_watch do
+  Dir.chdir("lib/interpol/documentation_app") do
+    sh "bundle exec compass watch"
+  end
+end
+
+desc "Import the twitter bootstrap assets from the compass_twitter_bootstrap gem"
+task :import_bootstrap_assets do
+  require 'bundler'
+  Bundler.setup
+
+  # when the gem installed as a :git gem, it has "-" as a separator;
+  # when it's installed as a released rubygem, it has "_" as a separator.
+  gem_lib_path = $LOAD_PATH.grep(/compass[-_]twitter[-_]bootstrap/).first
+  assets = Dir[File.join(gem_lib_path, '..', 'vendor', 'assets', '**')]
+
+  destination_path = File.expand_path("../lib/interpol/documentation_app/public", __FILE__)
+  FileUtils.cp_r(assets, destination_path)
+end
+

data/lib/interpol/configuration.rb

@@ -26,7 +26,7 @@ module Interpol
   # Public: Defines interpol configuration.
   class Configuration
     attr_reader :endpoint_definition_files, :endpoints
-    attr_accessor :validation_mode
+    attr_accessor :validation_mode, :documentation_title
 
     def initialize
       api_version do
@@ -46,6 +46,7 @@ module Interpol
       end
 
       self.endpoint_definition_files = []
+      self.documentation_title = "API Documentation Provided by Interpol"
       yield self if block_given?
     end
 

data/lib/interpol/documentation.rb

@@ -0,0 +1,72 @@
+require 'nokogiri'
+
+module Interpol
+  module Documentation
+    extend self
+
+    def html_for_schema(schema)
+      ForSchemaDefinition.new(schema).to_html
+    end
+
+    # Renders the documentation for a schema definition.
+    class ForSchemaDefinition
+      def initialize(schema)
+        @schema = schema
+      end
+
+      def to_html
+        build do |doc|
+          schema_definition(doc, @schema)
+        end.to_html
+      end
+
+    private
+
+      def build
+        Nokogiri::HTML::DocumentFragment.parse("").tap do |doc|
+          Nokogiri::HTML::Builder.with(doc) do |doc|
+            yield doc
+          end
+        end
+      end
+
+      def schema_description(doc, schema)
+        return unless schema.has_key?('description')
+        doc.h3(class: "description") { doc.text(schema['description']) }
+      end
+
+      def schema_definition(doc, schema)
+        doc.div(class: "schema-definition") do
+          schema_description(doc, schema)
+          render_properties(doc, Array(schema['properties']))
+        end
+      end
+
+      def render_properties(doc, properties)
+        return if properties.none?
+
+        doc.dl(class: "properties") do
+          properties.each do |name, property|
+            property_definition(doc, name, property)
+          end
+        end
+      end
+
+      def property_definition(doc, name, property)
+        doc.dt(class: "name") { doc.text(property_title name, property) }
+
+        if property.has_key?('description')
+          doc.dd { doc.text(property['description']) }
+        end
+
+        render_properties(doc, Array(property['properties']))
+      end
+
+      def property_title(name, property)
+        return name unless property['type']
+        "#{name} (#{property['type']})"
+      end
+    end
+  end
+end
+

data/lib/interpol/documentation_app.rb

@@ -0,0 +1,103 @@
+require 'interpol'
+require 'interpol/documentation'
+require 'sinatra/base'
+require 'nokogiri'
+
+module Interpol
+  module DocumentationApp
+    extend self
+
+    def build(&block)
+      config = Configuration.default.customized_duplicate(&block)
+      Builder.new(config).app
+    end
+
+    def render_static_page(&block)
+      require 'rack/mock'
+      app = build(&block)
+      status, headers, body = app.call(Rack::MockRequest.env_for "/", method: "GET")
+      AssetInliner.new(body.join, app.public_folder).standalone_page
+    end
+
+    # Inlines the assets so the page can be viewed as a standalone web page.
+    class AssetInliner
+      def initialize(page, asset_root)
+        @page, @asset_root = page, asset_root
+        @doc = Nokogiri::HTML(page)
+      end
+
+      def standalone_page
+        inline_stylesheets
+        inline_javascript
+        @doc.to_s
+      end
+
+    private
+
+      def inline_stylesheets
+        @doc.css("link[rel=stylesheet]").map do |link|
+          inline_asset link, "style", link['href'], type: "text/css"
+        end
+      end
+
+      def inline_javascript
+        @doc.css("script[src]").each do |script|
+          inline_asset script, "script", script['src'], type: "text/javascript"
+        end
+      end
+
+      def contents_for(asset)
+        File.read(File.join(@asset_root, asset))
+      end
+
+      def inline_asset(tag, tag_type, filename, attributes = {})
+        inline_tag = Nokogiri::XML::Node.new(tag_type, @doc)
+        attributes.each { |k, v| inline_tag[k] = v }
+        inline_tag.content = contents_for(filename)
+        tag.add_next_sibling(inline_tag)
+        tag.remove
+      end
+    end
+
+  private
+
+    module Helpers
+      def interpol_config
+        self.class.interpol_config
+      end
+
+      def endpoints
+        interpol_config.endpoints
+      end
+
+      def current_endpoint
+        endpoints.first
+      end
+
+      def title
+        interpol_config.documentation_title
+      end
+    end
+
+    # Private: Builds a stub sinatra app for the given interpol
+    # configuration.
+    class Builder
+      attr_reader :app
+
+      def initialize(config)
+        @app = Sinatra.new do
+          dir = File.dirname(File.expand_path(__FILE__))
+          set :views, "#{dir}/documentation_app/views"
+          set :public_folder, "#{dir}/documentation_app/public"
+          set :interpol_config, config
+          helpers Helpers
+
+          get('/') do
+            erb :layout, locals: { endpoints: endpoints, current_endpoint: current_endpoint }
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/interpol/documentation_app/config.rb

@@ -0,0 +1,24 @@
+# Require any additional compass plugins here.
+require 'compass_twitter_bootstrap'
+
+# Set this to the root of your project when deployed:
+http_path = "/"
+css_dir = "public/stylesheets"
+sass_dir = "sass"
+images_dir = "public/images"
+javascripts_dir = "public/javascripts"
+
+# You can select your preferred output style here (can be overridden via the command line):
+# output_style = :expanded or :nested or :compact or :compressed
+
+# To enable relative paths to assets via compass helper functions. Uncomment:
+relative_assets = true
+
+# To disable debugging comments that display the original location of your selectors. Uncomment:
+line_comments = false
+
+# If you prefer the indented syntax, you might want to regenerate this
+# project again passing --syntax sass, or you can uncomment this:
+# preferred_syntax = :sass
+# and then run:
+# sass-convert -R --from scss --to sass sass scss && rm -rf sass && mv scss sass

data/lib/interpol/endpoint.rb

@@ -24,6 +24,7 @@ module Interpol
       @route       = fetch_from(endpoint_hash, 'route')
       @method      = fetch_from(endpoint_hash, 'method').downcase.to_sym
       @definitions = extract_definitions_from(endpoint_hash)
+      validate_name!
     end
 
     def find_definition!(version)
@@ -76,6 +77,13 @@ module Interpol
 
       definitions
     end
+
+    def validate_name!
+      unless name =~ /\A[\w\-]+\z/
+        raise ArgumentError, "Invalid endpoint name (#{name.inspect}). "+
+                             "Only letters, numbers, underscores and dashes are allowed."
+      end
+    end
   end
 
   # Wraps a single versioned definition for an endpoint.

data/lib/interpol/version.rb

@@ -1,3 +1,3 @@
 module Interpol
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: interpol
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-05 00:00:00.000000000 Z
+date: 2012-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
-  requirement: &2155991900 !ruby/object:Gem::Requirement
+  requirement: &2152438820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -24,10 +24,10 @@ dependencies:
         version: 2.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2155991900
+  version_requirements: *2152438820
 - !ruby/object:Gem::Dependency
   name: json-schema
-  requirement: &2155989620 !ruby/object:Gem::Requirement
+  requirement: &2152437840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -35,10 +35,21 @@ dependencies:
         version: 1.0.5
   type: :runtime
   prerelease: false
-  version_requirements: *2155989620
+  version_requirements: *2152437840
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: &2152437180 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2152437180
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2155987560 !ruby/object:Gem::Requirement
+  requirement: &2152436180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -46,10 +57,10 @@ dependencies:
         version: '2.9'
   type: :development
   prerelease: false
-  version_requirements: *2155987560
+  version_requirements: *2152436180
 - !ruby/object:Gem::Dependency
   name: rspec-fire
-  requirement: &2155985640 !ruby/object:Gem::Requirement
+  requirement: &2152435480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -57,10 +68,10 @@ dependencies:
         version: '0.4'
   type: :development
   prerelease: false
-  version_requirements: *2155985640
+  version_requirements: *2152435480
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &2155984820 !ruby/object:Gem::Requirement
+  requirement: &2152434900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -68,10 +79,10 @@ dependencies:
         version: '0.6'
   type: :development
   prerelease: false
-  version_requirements: *2155984820
+  version_requirements: *2152434900
 - !ruby/object:Gem::Dependency
   name: cane
-  requirement: &2155983800 !ruby/object:Gem::Requirement
+  requirement: &2152433580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -79,10 +90,10 @@ dependencies:
         version: '1.2'
   type: :development
   prerelease: false
-  version_requirements: *2155983800
+  version_requirements: *2152433580
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2151940960 !ruby/object:Gem::Requirement
+  requirement: &2152433060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -90,10 +101,10 @@ dependencies:
         version: 0.9.2.2
   type: :development
   prerelease: false
-  version_requirements: *2151940960
+  version_requirements: *2152433060
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &2151939280 !ruby/object:Gem::Requirement
+  requirement: &2152432580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -101,7 +112,7 @@ dependencies:
         version: 0.6.1
   type: :development
   prerelease: false
-  version_requirements: *2151939280
+  version_requirements: *2152432580
 description: Interpol is a toolkit for working with API endpoint definition files,
   giving you a stub app, a schema validation middleware, and browsable documentation.
 email:
@@ -115,6 +126,9 @@ files:
 - Gemfile
 - Rakefile
 - lib/interpol/configuration.rb
+- lib/interpol/documentation.rb
+- lib/interpol/documentation_app/config.rb
+- lib/interpol/documentation_app.rb
 - lib/interpol/endpoint.rb
 - lib/interpol/errors.rb
 - lib/interpol/response_schema_validator.rb